expressir 2.4.3 → 2.4.4

data/lib/expressir/model/concerns.rb

@@ -22,7 +22,21 @@ module Expressir
     # Marker for types supporting where rules
     module HasWhereRules; end
 
+    # Marker for types that can own a remark written after them on the same
+    # line, as in `x := 1; -- why`. Includers are ModelElements, so they all
+    # carry the `untagged_remarks` collection the remark is stored in.
+    #
+    # Attachment and formatting must agree on this exactly: a type the
+    # attacher marks INLINE but the formatter declines to emit loses the
+    # remark with nothing to show for it. Both ask this one question.
+    #
+    # Not the same question as NodePositionIndex#remark_scope?, which decides
+    # who owns a remark on a line of its OWN.
+    module TakesInlineRemark; end
+
     # Marker for executable statements (ISO 10303-11 section 13)
-    module Statement; end
+    module Statement
+      include TakesInlineRemark
+    end
   end
 end

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

@@ -17,7 +17,12 @@ module Expressir
         attribute :abstract, :boolean
         attribute :supertype_expression, ModelElement
         attribute :subtype_of, ModelElement, collection: true
-        attribute :attributes, Attribute, collection: true
+        # Heterogeneous by design: Attribute, DerivedAttribute, and
+        # InverseAttribute all live here (the builders concatenate the
+        # three clauses in declaration order). The ModelElement base
+        # keeps from_hash polymorphic via the _class marker, exactly
+        # like the Ruby-built model.
+        attribute :attributes, ModelElement, collection: true
         attribute :derived_attributes, DerivedAttribute, collection: true
         attribute :inverse_attributes, InverseAttribute, collection: true
         attribute :unique_rules, UniqueRule, collection: true

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

@@ -4,6 +4,9 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 11 Interface specification
       class Interface < ModelElement
+        # A remark may trail the clause: `REFERENCE FROM x; -- why`.
+        include TakesInlineRemark
+
         USE = "USE".freeze
         REFERENCE = "REFERENCE".freeze
 
@@ -12,11 +15,21 @@ module Expressir
         attribute :items, InterfaceItem, collection: true
         attribute :_class, :string, default: -> { self.class.name }
 
+        # Registers :items with the tree-walker registry: the position index
+        # needs the item list to size the clause's span, so an opener-line
+        # remark gets the OPENER_REGION and renders back on the clause's
+        # first line instead of after the closing semicolon.
+        collection_attributes :items
+
         key_value do
           map "_class", to: :_class, render_default: true
           map "kind", to: :kind
           map "schema", to: :schema
           map "items", to: :items
+          # Without this the clause's remark survives a format but not a
+          # cache round trip: it would be dropped on serialization and never
+          # come back.
+          map "untagged_remarks", to: :untagged_remarks
         end
       end
     end

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

@@ -9,7 +9,7 @@ module Expressir
 
         # Tree-walker collection attributes (TODO.bugs/12 — single source
         # of truth; NodePositionIndex derives COLLECTION_REGISTRY from this).
-        collection_attributes :constants, :types, :entities,
+        collection_attributes :interfaces, :constants, :types, :entities,
                               :subtype_constraints, :functions, :rules,
                               :procedures, :remark_items
 
@@ -60,6 +60,7 @@ module Expressir
           map :header, to: :header
           map :formatted, to: :formatted
           map :source, to: :source
+          map :source_hyperlinked, to: :source_hyperlinked
           map :full_source, to: :full_source
           map :children, to: :children
           map :safe_children, to: :safe_children
@@ -96,8 +97,18 @@ module Expressir
           @formatted ||= format(no_remarks: false)
         end
 
+        # Schema head text without hyperlinks (#255) — the `source` face
+        # templates call for the verbatim schema declaration block.
+        # Deliberately NOT @source: that ivar holds the raw source span
+        # lutaml-model's `source=` stores when include_source is on.
         def source
-          @source ||= Expressir::Express::SchemaSourceFormatter.format(self)
+          @plain_source ||= Expressir::Express::SchemaPlainSourceFormatter.format(self) # rubocop:disable Naming/MemoizedInstanceVariableName
+        end
+
+        # Schema head text with cross-references rendered as hyperlinks
+        # (#255) — the hyperlinked counterpart of #source.
+        def source_hyperlinked
+          Expressir::Express::SchemaSourceFormatter.format(self)
         end
 
         private
@@ -118,30 +129,70 @@ module Expressir
         def interfaced_items
           return [] unless parent
 
+          visited_schemas = {}
           interfaces.flat_map do |interface|
-            schema = parent.children_by_id[interface.schema.id.safe_downcase]
-            next [] unless schema
-
-            safe_children = schema.safe_children
-            children_by_id = safe_children.each_with_object({}) do |child, hash|
-              hash[child.id.safe_downcase] = child if child.id
-            end
-
-            if interface.items.empty?
-              safe_children.map do |base_item|
-                create_interfaced_item(base_item.id, base_item)
-              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
-              end
-            end
+            items_for_interface(interface, visited_schemas)
           end.compact
         end
+
+        # 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).
+        def items_for_interface(interface, visited_schemas)
+          schema = foreign_schema(interface.schema.id.safe_downcase)
+          return [] unless schema
+          # Visited means this schema's contribution is already in the
+          # caller's result: re-entering — mutual USE FROM included —
+          # recursed forever when the interface carried an item list
+          # (the old guard only fired for the list-less form).
+          return [] if visited_schemas.key?(schema.id.safe_downcase)
+
+          visited_schemas[schema.id.safe_downcase] = true
+
+          safe_children = schema.safe_children
+          children_by_id = safe_children.each_with_object({}) do |child, hash|
+            hash[child.id.safe_downcase] = child if child.id
+          end
+
+          own = if interface.items.empty?
+                  safe_children.map do |base_item|
+                    create_interfaced_item(base_item.id, base_item)
+                  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
+                  end
+                end
+
+          # Transitive items are not restricted by this interface's
+          # item list: implicit interfacing through USE is unfiltered
+          # (eeng :use-only → :use-from recursion finds any id in the
+          # foreign schema's use scope).
+          own + Array(schema.interfaces).filter_map do |foreign_iface|
+            next nil unless foreign_iface.kind == Interface::USE
+
+            foreign_items = items_for_interface(foreign_iface,
+                                                visited_schemas)
+            foreign_items.empty? ? nil : foreign_items
+          end.flatten
+        end
+
+        # Find a foreign schema by name: same file first, then the
+        # enclosing repository (expressir's compiled/batch repository).
+        def foreign_schema(name)
+          current = parent
+          while current
+            return current.children_by_id[name] if current.respond_to?(:children_by_id) &&
+              current.children_by_id[name]
+
+            current = current.is_a?(ModelElement) ? current.parent : nil
+          end
+          nil
+        end
       end
     end
   end

data/lib/expressir/model/indexes/item_graph.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Model
+    module Indexes
+      # Item-level graph over a resolved repository: nodes are schema
+      # items (canonical "schema.item" paths), edges are inheritance,
+      # interface imports, and attribute-type references.
+      #
+      # {Model::ModelElement#path} is file-qualified and empty for
+      # id-less nodes, so node identity is the last two path segments —
+      # unique because schema names are unique within a repository.
+      class ItemGraph
+        attr_reader :nodes, :subtype_of, :dependencies
+
+        # @param repository [Repository] a resolved repository
+        def initialize(repository)
+          @nodes = {}
+          @subtype_of = Hash.new { |h, k| h[k] = [] }
+          @dependencies = Hash.new { |h, k| h[k] = [] }
+          build(repository)
+        end
+
+        # Plain tables for artifact persistence — node keys only, no
+        # model references. `ItemGraph.from_tables` is the zero-model
+        # counterpart used on warm loads.
+        def tables
+          {
+            "nodes" => @nodes.keys,
+            "subtype_of" => @subtype_of.reject { |_, parents| parents.empty? },
+            "dependencies" => @dependencies.reject { |_, deps| deps.empty? },
+          }
+        end
+
+        def self.from_tables(tables)
+          graph = allocate
+          graph.instance_variable_set(:@nodes, tables["nodes"].to_h { |k| [k, nil] })
+          graph.instance_variable_set(
+            :@subtype_of,
+            Hash.new { |h, k| h[k] = [] }.update(tables["subtype_of"] || {}),
+          )
+          graph.instance_variable_set(
+            :@dependencies,
+            Hash.new { |h, k| h[k] = [] }.update(tables["dependencies"] || {}),
+          )
+          graph
+        end
+
+        def include?(path)
+          @nodes.key?(canonical(path))
+        end
+
+        # Transitive supertype closure of an entity, breadth-first.
+        def supertypes(path)
+          key = canonical(path)
+          return [] unless @nodes.key?(key)
+
+          seen = {}
+          result = []
+          queue = @subtype_of[key].dup
+          until queue.empty?
+            current = queue.shift
+            next if seen[current]
+
+            seen[current] = true
+            result << current
+            queue.concat(@subtype_of[current])
+          end
+          result
+        end
+
+        # Schemas whose items `schema` imports (USE FROM / REFERENCE
+        # FROM), direct only. Accepts a schema object or its id.
+        def dependencies_of(schema)
+          schema_id = schema.respond_to?(:id) ? schema.id : schema.to_s
+          @dependencies[schema_id.safe_downcase].dup
+        end
+
+        def subtype_edges
+          @subtype_of.flat_map { |child, parents| parents.map { |p| [child, p] } }
+        end
+
+        def cross_schema_subtype_edges
+          subtype_edges.count { |child, parent| child.split(".")[0] != parent.split(".")[0] }
+        end
+
+        private
+
+        def canonical(path)
+          return nil unless path
+
+          parts = path.to_s.split(".")
+          return nil if parts.size < 2
+
+          parts[-2, 2].join(".").safe_downcase
+        end
+
+        def build(repository)
+          # Nodes register before their subtype edges: subtype references
+          # may be unresolved (the declaring schema is not in the
+          # repository), and an edge to a node that does not exist would
+          # surface as a phantom path in supertype closures.
+          edges = []
+          repository.schemas.each do |schema|
+            schema_id = schema.id.safe_downcase
+            schema.entities.to_a.each do |entity|
+              key = node_key(schema_id, entity)
+              @nodes[key] = entity
+              edges << [key, schema_id, entity]
+            end
+            schema.types.to_a.each do |type|
+              @nodes[node_key(schema_id, type)] = type
+            end
+            schema.interfaces.to_a.each do |interface|
+              target = interface.schema.is_a?(String) ? interface.schema : interface.schema&.id
+              next unless target
+
+              @dependencies[schema_id] << target.safe_downcase
+            end
+          end
+          edges.each do |key, schema_id, entity|
+            entity.subtype_of.to_a.each do |ref|
+              parent = ref.base_path ? canonical(ref.base_path) : "#{schema_id}.#{ref.id.safe_downcase}"
+              @subtype_of[key] << parent if parent && @nodes.key?(parent)
+            end
+          end
+        end
+
+        def node_key(schema_id, element)
+          canonical(element.path) || "#{schema_id}.#{element.id.safe_downcase}"
+        end
+      end
+    end
+  end
+end

data/lib/expressir/model/indexes.rb

@@ -6,6 +6,7 @@ module Expressir
       autoload :EntityIndex, "#{__dir__}/indexes/entity_index"
       autoload :TypeIndex, "#{__dir__}/indexes/type_index"
       autoload :ReferenceIndex, "#{__dir__}/indexes/reference_index"
+      autoload :ItemGraph, "#{__dir__}/indexes/item_graph"
     end
   end
 end

data/lib/expressir/model/model_element.rb

@@ -61,7 +61,11 @@ module Expressir
 
       # ---- End child-attributes macro ----
 
-      SKIP_ATTRIBUTES = %i[parent _class].freeze
+      # :source is skipped deliberately: its reader formats the node,
+      # and reading it during construction (attach_parent_to_children on
+      # a from_hash-built object whose attributes are not yet applied)
+      # would memoize an incomplete rendering forever.
+      SKIP_ATTRIBUTES = %i[parent _class source].freeze
       # :parent is a special attribute that is used to store the parent of the current element
       # It is not a real attribute
       # attribute :parent, ModelElement
@@ -101,6 +105,7 @@ module Expressir
         "Expressir::Model::Declarations::Entity" => "Expressir::Model::Declarations::Entity",
         "Expressir::Model::Declarations::Function" => "Expressir::Model::Declarations::Function",
         "Expressir::Model::Declarations::InterfaceItem" => "Expressir::Model::Declarations::InterfaceItem",
+        "Expressir::Model::Declarations::InverseAttribute" => "Expressir::Model::Declarations::InverseAttribute",
         "Expressir::Model::Declarations::Interface" => "Expressir::Model::Declarations::Interface",
         "Expressir::Model::Declarations::InterfacedItem" => "Expressir::Model::Declarations::InterfacedItem",
         "Expressir::Model::Declarations::Parameter" => "Expressir::Model::Declarations::Parameter",
@@ -152,6 +157,10 @@ module Expressir
       key_value do
         map "_class", to: :_class, render_default: true,
                       polymorphic_map: POLYMORPHIC_CLASS_MAP
+        # Hydrate-only: byte positions ride the wire (Rust core path)
+        # without ever appearing in to_hash — the serialized shape stays
+        # identical to the Ruby-built model.
+        map "source_offset", to: :source_offset, serialize: false
       end
 
       def source
@@ -278,6 +287,24 @@ module Expressir
         end
       end
 
+      # Wire the parent pointers of this node's entire subtree. Needed
+      # for models materialized outside the builders (e.g. hydrated
+      # from the Rust core path), whose parents start unset.
+      def wire_parents(parent = nil)
+        self.parent = parent
+        self.class.attributes.each_key do |attr|
+          next if SKIP_ATTRIBUTES.include?(attr) || attr == :parent
+
+          value = public_send(attr)
+          case value
+          when Array
+            value.each { |v| v.wire_parents(self) if v.is_a?(ModelElement) }
+          when ModelElement
+            value.wire_parents(self)
+          end
+        end
+      end
+
       # @return [Array<Declaration>]
       def children
         []
@@ -327,6 +354,8 @@ module Expressir
       # @return [nil]
       def attach_parent_to_children
         self.class.attributes.each_pair do |symbol, _lutaml_attr|
+          next if SKIP_ATTRIBUTES.include?(symbol)
+
           value = public_send(symbol)
 
           case value

data/lib/expressir/model/remark_info.rb

@@ -9,7 +9,10 @@ module Expressir
       attribute :tag, :string # optional remark tag like "entity.attr"
       # See RemarkPlacement. nil = legacy placement.
       attribute :placement, :string
-      # For TRAILING remarks, which body of the owner they close.
+      # Qualifies the placement. For TRAILING, which body of the owner the
+      # remark closes, named by that body's attribute. For INLINE,
+      # RemarkPlacement::OPENER_REGION when it trailed a compound statement's
+      # opening line rather than a whole statement.
       attribute :region, :string
       attribute :source_offset, :integer # byte offset in source text
 
@@ -43,6 +46,22 @@ module Expressir
         placement == RemarkPlacement::INLINE
       end
 
+      # Check if this remark trailed the opening line of a statement spanning
+      # several lines, as in `IF x THEN -- why`
+      # @return [Boolean]
+      def opener?
+        inline? && region == RemarkPlacement::OPENER_REGION
+      end
+
+      # Check if this INLINE remark belongs after a mid-construct keyword of
+      # its owning construct — `ELSE -- why`, `OTHERWISE : -- why` — rather
+      # than after the statement's closing keyword.
+      # @param name [Symbol, String] a RemarkPlacement region constant
+      # @return [Boolean]
+      def inline_region?(name)
+        inline? && region == name.to_s
+      end
+
       # Check if this remark closes the given body of its owning node
       # @param name [Symbol, String] region attribute name
       # @return [Boolean]

data/lib/expressir/model/remark_placement.rb

@@ -14,8 +14,11 @@ module Expressir
     #   keyword. The owner is the body's owner, and RemarkInfo#region names
     #   which body: an IF owns two, and they close at different keywords.
     # - INLINE — on the same line as the owning statement, after its text.
-    #   Only single-line statements take these: appending to a multi-line
-    #   statement would move the remark down to its closing keyword.
+    #   Emitted after the whole statement, which for a single-line one is the
+    #   line it was written on. RemarkInfo#region separates the other case:
+    #   OPENER_REGION means the remark trailed the opening line of a statement
+    #   spanning several lines, as in `IF x THEN -- why`, and belongs back on
+    #   that opener rather than after the closing keyword.
     #
     # `nil` means the remark was attached by a legacy path, or predates
     # placement tracking. Those keep their historical emission and must not
@@ -24,6 +27,16 @@ module Expressir
       LEADING = "leading"
       TRAILING = "trailing"
       INLINE = "inline"
+
+      # Region of an INLINE remark that trailed a compound statement's opener.
+      OPENER_REGION = "opener"
+
+      # Regions of INLINE remarks that trailed a mid-construct keyword line —
+      # `ELSE -- why` or `OTHERWISE : -- why`. The owning construct is the
+      # enclosing IF / CASE, and the remark belongs back after that keyword,
+      # not after the construct's closing END_.
+      ELSE_REGION = "else"
+      OTHERWISE_REGION = "otherwise"
     end
   end
 end

data/lib/expressir/model/repository.rb

@@ -24,6 +24,10 @@ module Expressir
       # Index instances (lazy-loaded)
       attr_reader :entity_index, :type_index, :reference_index
 
+      # Item-level graph; loaded from the compiled-set artifact on
+      # warm starts, built on demand otherwise.
+      attr_accessor :item_graph
+
       # Restore deserialized indexes (used by Package::Reader)
       def restore_indexes(entity_index: nil, type_index: nil,
 reference_index: nil)
@@ -56,10 +60,12 @@ reference_index: nil)
         schemas&.each { |schema| @_schemas << schema }
       end
 
-      # Get all schemas (from both files and direct storage)
+      # Get all schemas (from both files and direct storage).
+      # Files that failed to parse are nil in `files` — a parse failure must
+      # not crash schema enumeration with a NoMethodError from in here.
       # @return [Array<Declarations::Schema>]
       def schemas
-        file_schemas = files&.flat_map(&:schemas)&.compact || []
+        file_schemas = files.compact.flat_map(&:schemas).compact
         file_schemas + @_schemas
       end
 

data/lib/expressir/model.rb

@@ -3,13 +3,14 @@
 module Expressir
   module Model
     # Marker modules — autoload the same concerns.rb file from each name.
-    # The first reference triggers the load; the file defines all seven markers.
+    # The first reference triggers the load; the file defines all eight markers.
     autoload :HasId, "#{__dir__}/model/concerns"
     autoload :HasRemarkItems, "#{__dir__}/model/concerns"
     autoload :HasRemarks, "#{__dir__}/model/concerns"
     autoload :ScopeContainer, "#{__dir__}/model/concerns"
     autoload :HasInformalPropositions, "#{__dir__}/model/concerns"
     autoload :HasWhereRules, "#{__dir__}/model/concerns"
+    autoload :TakesInlineRemark, "#{__dir__}/model/concerns"
     autoload :Statement, "#{__dir__}/model/concerns"
 
     autoload :ModelElement, "#{__dir__}/model/model_element"

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.3".freeze
+    VERSION = "2.4.4".freeze
   end
 end

data/lib/tasks/verify_remarks.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# `rake verify:remarks` — the remark conservation gate. Runs only the
+# production-scale checks (`:production_scale` tag; see spec_helper's
+# filter), which the default suite excludes: they parse a full-size
+# schema and cost about a minute.
+RSpec::Core::RakeTask.new(:"verify:remarks") do |task|
+  task.rspec_opts = "--tag production_scale"
+end

data/rakelib/verify_remarks.rake

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+namespace :verify do
+  desc "Check remarks against the recorded round-trip gaps, production included"
+  task :remarks do
+    specs = %w[
+      spec/expressir/remark_conservation_spec.rb
+      spec/expressir/remark_ownership_spec.rb
+      spec/expressir/express/formatter_remark_conservation_spec.rb
+      spec/expressir/express/formatter_remark_ownership_spec.rb
+    ]
+
+    sh({ "EXPRESSIR_PRODUCTION_SCALE" => "1" },
+       "bundle", "exec", "rspec", *specs)
+  end
+end