lutaml-model 0.8.17 → 0.8.18

data/lib/lutaml/model/schema/rng_compiler/element_visitor.rb

@@ -0,0 +1,392 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Schema
+      module RngCompiler
+        # Walks an RNG <element> / <define> subtree and produces
+        # Definitions::Model / Definitions::RestrictedType / Definitions::UnionType
+        # objects, registered in the shared `classes` hash.
+        #
+        # Supported constructs:
+        #   element, attribute, ref, text, data, value, empty,
+        #   optional, zeroOrMore, oneOrMore, group, choice, mixed, list,
+        #   interleave
+        #
+        # Shape classification (define-wraps-data, define-wraps-enum-choice,
+        # union) is delegated to DefineClassifier. Value-shape resolution
+        # for individual children is delegated to ValueTypeResolver.
+        class ElementVisitor
+          DISPATCHABLE_KINDS = %i[
+            element attribute ref group optional oneOrMore zeroOrMore
+            choice list interleave empty
+          ].freeze
+
+          REPETITION_CTX = {
+            zeroOrMore: { collection: (0..Float::INFINITY), initialize_empty: true },
+            oneOrMore: { collection: (1..Float::INFINITY), initialize_empty: true },
+            list: { collection: (0..Float::INFINITY), initialize_empty: true },
+          }.freeze
+
+          HANDLERS = {
+            element: :handle_element,
+            attribute: :handle_attribute,
+            ref: :handle_ref,
+            group: :handle_group,
+            optional: :handle_optional,
+            oneOrMore: :handle_repeating,
+            zeroOrMore: :handle_repeating,
+            list: :handle_repeating,
+            choice: :handle_choice,
+            interleave: :handle_interleave,
+            empty: :handle_empty,
+          }.freeze
+
+          def initialize(defines, classes, default_namespace_class: nil,
+                         register_namespace: nil)
+            @defines = defines
+            @classes = classes
+            @default_namespace_class = default_namespace_class
+            @register_namespace = register_namespace
+            @value_type_resolver = ValueTypeResolver.new(
+              defines, classes,
+              compile_define: method(:compile_define),
+              register_class: method(:register_class!)
+            )
+          end
+
+          # Compile a top-level <element>. Always becomes a rooted model.
+          def compile_element(element)
+            class_name = Utils.camel_case(element.attr_name)
+            model = @classes[class_name] ||= Definitions::Model.new(
+              class_name: class_name,
+              xml_root: Definitions::XmlRoot.new(kind: :element, name: element.attr_name),
+              documentation: documentation_text(element),
+              namespace_class_name: namespace_class_for(element),
+            )
+            visit_content(element, model)
+            model
+          end
+
+          # Compile a <define> into a class.
+          # - Define body matches a simple-type shape -> RestrictedType/UnionType.
+          # - Wraps exactly one element                -> rooted Definitions::Model.
+          # - Multiple or zero wrapped elements        -> fragment Definitions::Model.
+          def compile_define(define)
+            class_name = Utils.camel_case(define.name)
+            return @classes[class_name] if @classes.key?(class_name)
+
+            if (simple = DefineClassifier.build(define, class_name))
+              register_class!(simple)
+              return simple
+            end
+
+            build_complex_define(define, class_name)
+          end
+
+          private
+
+          def build_complex_define(define, class_name)
+            wrapping = define.element.size == 1 ? define.element.first : nil
+
+            xml_root = if wrapping
+                         Definitions::XmlRoot.new(kind: :element, name: wrapping.attr_name)
+                       else
+                         Definitions::XmlRoot.new(kind: :fragment)
+                       end
+
+            model = Definitions::Model.new(
+              class_name: class_name,
+              xml_root: xml_root,
+              documentation: documentation_text(define) || documentation_text(wrapping),
+              namespace_class_name: namespace_class_for(wrapping || define),
+            )
+            register_class!(model)
+            visit_content(wrapping || define, model)
+            model
+          end
+
+          def register_class!(klass)
+            @classes[klass.class_name] = klass
+          end
+
+          # A node's foreign XML namespace URI, or nil. An empty `ns` (RNC's
+          # `ns=""` no-namespace override) and the built-in "xml" prefix are
+          # both treated as not foreign, so `namespace_class_for` hands the
+          # node the grammar default namespace. lutaml expresses namespaces
+          # only at class level, so a per-node `ns=""` override cannot be
+          # represented distinctly from the default and is not separately
+          # honored -- excluding "" here just avoids registering a bogus
+          # empty-URI namespace that would clobber the grammar default.
+          def foreign_namespace_uri(node)
+            uri = node.respond_to?(:ns) ? node.ns : nil
+            uri if uri.is_a?(String) && !uri.empty? && uri != "xml"
+          end
+
+          # An element's own ns (from `element ex:name`) becomes its model's
+          # class-level namespace; otherwise it inherits the grammar default.
+          def namespace_class_for(node)
+            uri = foreign_namespace_uri(node)
+            uri ? @register_namespace.call(uri) : @default_namespace_class
+          end
+
+          def documentation_text(node)
+            return nil unless node.respond_to?(:documentation)
+
+            docs = Array(node.documentation).map(&:to_s).reject(&:empty?)
+            docs.empty? ? nil : docs.join("\n")
+          end
+
+          # Generic content walker.
+          def visit_content(node, model, ctx = default_ctx)
+            ordered_children(node).each do |kind, child|
+              dispatch(kind, child, model, ctx)
+            end
+
+            model.mixed = true if mixed?(node)
+            model.text_content = true if text?(node)
+          end
+
+          def default_ctx
+            { collection: nil, initialize_empty: false }
+          end
+
+          def ordered_children(node)
+            element_entries = element_order_entries(node)
+            return fallback_each_child_kind(node) if element_entries.empty?
+
+            arrays = {}
+            indices = ::Hash.new(0)
+            element_entries.each_with_object([]) do |entry, pairs|
+              kind = entry.name.to_sym
+              next unless DISPATCHABLE_KINDS.include?(kind) && node.respond_to?(kind)
+
+              children = arrays[kind] ||= Array(node.public_send(kind))
+              child = children[indices[kind]]
+              indices[kind] += 1
+              pairs << [kind, child] if child
+            end
+          end
+
+          def element_order_entries(node)
+            return [] unless node.respond_to?(:element_order)
+
+            Array(node.element_order).select do |e|
+              e.respond_to?(:node_type) && e.node_type == :element
+            end
+          end
+
+          def fallback_each_child_kind(node)
+            DISPATCHABLE_KINDS.each_with_object([]) do |attr_name, pairs|
+              next unless node.respond_to?(attr_name)
+
+              Array(node.public_send(attr_name)).each do |child|
+                pairs << [attr_name, child] unless child.nil?
+              end
+            end
+          end
+
+          def dispatch(kind, child, parent, ctx)
+            handler = HANDLERS[kind] or return
+
+            send(handler, kind, child, parent, ctx)
+          end
+
+          # --- handlers ---------------------------------------------------
+
+          def handle_element(_kind, child, parent, ctx)
+            doc = documentation_text(child)
+            value_type = @value_type_resolver.resolve(child)
+            type_ref = type_ref_for_element(child, value_type)
+            push_attribute(parent, build_attribute(child, type_ref, :element, ctx, doc))
+          end
+
+          def type_ref_for_element(child, value_type)
+            return Definitions::TypeRef.new(kind: :symbol, value: value_type.to_s) if value_type
+
+            compiled = compile_element(child)
+            Definitions::TypeRef.new(kind: :class_ref, value: compiled.class_name)
+          end
+
+          def handle_attribute(_kind, child, parent, ctx)
+            doc = documentation_text(child)
+            symbol = attribute_type_symbol(child)
+            type_ref = Definitions::TypeRef.new(kind: :symbol, value: symbol.to_s)
+            fixed = fixed_value_default(child)
+            push_attribute(parent, build_attribute(child, type_ref, :attribute, ctx, doc, default: fixed))
+          end
+
+          # The attribute's value type, as a Symbol. An attribute in a foreign
+          # namespace (a prefix other than the built-in "xml") must carry that
+          # namespace, which lutaml-model expresses only through a Type::Value
+          # subclass — so wrap the value in a generated namespaced type.
+          def attribute_type_symbol(child)
+            base = @value_type_resolver.resolve(child) || :string
+            uri = foreign_namespace_uri(child)
+            return base unless uri
+
+            namespaced_attribute_type(child, base, @register_namespace.call(uri))
+          end
+
+          # Give the attribute's value a namespace via a dedicated generated
+          # type — never by mutating the resolved type, which may be a named
+          # define or an inline type shared with unqualified members. When the
+          # resolved base is itself a generated RestrictedType, subclass it so
+          # its constraints are inherited; otherwise subclass the built-in base.
+          def namespaced_attribute_type(child, base, ns_class)
+            resolved = generated_type_for(base)
+            parent = resolved ? resolved.class_name : RngHelpers.parent_class_for(base)
+
+            type = Definitions::RestrictedType.new(
+              class_name: RngHelpers.unique_class_name(
+                @classes, "#{Utils.camel_case(child.attr_name)}Type"
+              ),
+              parent_class: parent,
+              facets: Definitions::Facet.new,
+              namespace_class_name: ns_class,
+            )
+            register_class!(type)
+            RngHelpers.type_symbol(type.class_name)
+          end
+
+          # The generated RestrictedType a resolved type symbol refers to, found
+          # by symbol identity (so acronym class names round-trip) — or nil for a
+          # built-in symbol. A built-in symbol always means the built-in type,
+          # even if a define shares its name (a custom `dateTime` must not shadow
+          # the primitive `:date_time`).
+          def generated_type_for(base)
+            return nil if Lutaml::Model::Type::TYPE_CODES.key?(base)
+
+            @classes.values.find do |klass|
+              klass.is_a?(Definitions::RestrictedType) &&
+                RngHelpers.type_symbol(klass.class_name) == base
+            end
+          end
+
+          def build_attribute(child, type_ref, kind, ctx, doc, default: nil)
+            xml_name = xml_name_for(child)
+            Definitions::Attribute.new(
+              name: Utils.snake_case(xml_name.tr(":", "_")),
+              type: type_ref,
+              xml_name: xml_name,
+              kind: kind,
+              collection: ctx[:collection] || false,
+              initialize_empty: ctx[:initialize_empty] || false,
+              documentation: doc,
+              default: default,
+            )
+          end
+
+          def xml_name_for(child)
+            name = child.attr_name
+            ns = child.respond_to?(:ns) ? child.ns : nil
+            return name unless ns == "xml"
+
+            "#{ns}:#{name}"
+          end
+
+          # <attribute name="x"><value>X</value></attribute> = fixed value.
+          # Match XSD compiler's behavior — emit `default: -> { "X" }` so
+          # the value round-trips even when omitted.
+          def fixed_value_default(container)
+            return nil unless container.respond_to?(:value)
+
+            values = Array(container.value)
+            return nil if values.size != 1
+            return nil if RngHelpers.structural_content?(container)
+
+            values.first.value.to_s
+          end
+
+          def handle_ref(_kind, ref, parent, ctx)
+            target_define = @defines[ref.name]
+            raise Lutaml::Model::Error, "ref to unknown define: #{ref.name}" unless target_define
+
+            target_class = compile_define(target_define)
+
+            if RngHelpers.simple_type?(target_class)
+              type_ref = Definitions::TypeRef.new(kind: :symbol, value: RngHelpers.type_symbol(target_class.class_name).to_s)
+              push_attribute(parent, build_ref_attribute(ref, type_ref, ref.name, ctx))
+            elsif RngHelpers.fragment_model?(target_class) && ctx[:collection].nil?
+              push_import(parent, target_class.class_name)
+            else
+              type_ref = Definitions::TypeRef.new(kind: :class_ref, value: target_class.class_name)
+              xml_name = target_class.xml_root.name || ref.name
+              push_attribute(parent, build_ref_attribute(ref, type_ref, xml_name, ctx))
+            end
+          end
+
+          def build_ref_attribute(ref, type_ref, xml_name, ctx)
+            Definitions::Attribute.new(
+              name: Utils.snake_case(ref.name),
+              type: type_ref,
+              xml_name: xml_name,
+              kind: :element,
+              collection: ctx[:collection] || false,
+              initialize_empty: ctx[:initialize_empty] || false,
+            )
+          end
+
+          # <group> = ordered sequence of items.
+          def handle_group(_kind, group, parent, ctx)
+            collector = MemberCollector.new
+            visit_content(group, collector, ctx)
+            return if collector.members.empty?
+
+            parent.members << Definitions::Sequence.new(members: collector.members)
+            collector.imports.each { |name| push_import(parent, name) }
+          end
+
+          def handle_optional(_kind, opt, parent, ctx)
+            visit_content(opt, parent, ctx)
+          end
+
+          def handle_interleave(_kind, interleave, parent, ctx)
+            visit_content(interleave, parent, ctx)
+          end
+
+          def handle_repeating(kind, node, parent, ctx)
+            visit_content(node, parent, ctx.merge(REPETITION_CTX.fetch(kind)))
+          end
+
+          def handle_choice(_kind, choice, parent, ctx)
+            return if RngHelpers.pure_value_choice?(choice)
+
+            collector = MemberCollector.new
+            visit_content(choice, collector, ctx)
+            return if collector.members.empty?
+
+            parent.members << Definitions::Choice.new(
+              alternatives: collector.members,
+              header: "choice",
+            )
+            collector.imports.each { |name| push_import(parent, name) }
+          end
+
+          def handle_empty(_kind, _child, _parent, _ctx)
+            # <empty/> contributes no content — intentionally no-op.
+          end
+
+          def push_attribute(parent, attr)
+            parent.members.reject! do |m|
+              m.is_a?(Definitions::Attribute) && m.name == attr.name
+            end
+            parent.members << attr
+          end
+
+          def push_import(parent, name)
+            parent.imports << name unless parent.imports.include?(name)
+          end
+
+          def mixed?(node)
+            node.respond_to?(:mixed) && Utils.present?(node.mixed)
+          end
+
+          def text?(node)
+            node.respond_to?(:text) && Utils.present?(node.text)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/schema/rng_compiler/member_collector.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Schema
+      module RngCompiler
+        # Lightweight accumulator used by ElementVisitor when collecting the
+        # children of a transient construct (`<group>`, `<choice>`) before
+        # promoting them into a Definitions::Sequence or Definitions::Choice on
+        # the real Definitions::Model.
+        #
+        # Mirrors the surface ElementVisitor expects on a model
+        # (members, imports, mixed, text_content) but with no XML root,
+        # documentation, or namespace — none of which apply to a scratch
+        # container.
+        class MemberCollector
+          attr_reader :members, :imports
+          attr_accessor :mixed, :text_content
+
+          def initialize
+            @members = []
+            @imports = []
+            @mixed = false
+            @text_content = false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/schema/rng_compiler/rng_helpers.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Schema
+      module RngCompiler
+        # RNG-specific helpers used by ElementVisitor, DefineClassifier, and
+        # ValueTypeResolver. Centralising these here avoids the three-way
+        # semantic drift the first refactor introduced (e.g. inconsistent
+        # `pure_value_choice?` implementations).
+        module RngHelpers
+          module_function
+
+          # True if the compiled define renders as a value type (RestrictedType
+          # or UnionType) rather than its own Serializable class. Single
+          # source of truth — used by ElementVisitor and ValueTypeResolver.
+          def simple_type?(klass)
+            klass.is_a?(Definitions::RestrictedType) ||
+              klass.is_a?(Definitions::UnionType)
+          end
+
+          # True iff `klass` is a fragment model (no rooted xml element).
+          def fragment_model?(klass)
+            klass.is_a?(Definitions::Model) && klass.xml_root.kind == :fragment
+          end
+
+          # Returns the only element of a collection, or nil if the
+          # collection is empty or has more than one element. Treats nil as
+          # an empty collection.
+          def single(collection)
+            arr = Array(collection)
+            arr.size == 1 ? arr.first : nil
+          end
+
+          # An RNG node has structural content when any of its element /
+          # ref / attribute / choice / group / optional / repetition
+          # children are populated.
+          def structural_content?(node)
+            node && present_children?(node, STRUCTURAL_CHILD_NAMES)
+          end
+
+          # True iff any of `attrs` is a populated array-child of `node`.
+          def present_children?(node, attrs)
+            attrs.any? do |attr|
+              node.respond_to?(attr) && Array(node.public_send(attr)).any?
+            end
+          end
+
+          # True when `node` has branching structure that needs its own
+          # class. Pure value-choices and `<ref>`s to simple types are NOT
+          # branching — they're typed leaves.
+          def branching_structural?(node)
+            return false unless node
+
+            non_leaf = STRUCTURAL_CHILD_NAMES - %i[choice ref]
+            return true if present_children?(node, non_leaf)
+
+            return false unless node.respond_to?(:choice)
+
+            Array(node.choice).any? { |c| !pure_value_choice?(c) }
+          end
+
+          # True iff `choice` is a <choice> consisting purely of <value>
+          # alternatives (no <element>, <ref>, <data>, or <text>). A <text>
+          # alternative subsumes the literals, so `text | "x"` is a plain
+          # string, not an enum restricted to "x".
+          def pure_value_choice?(choice)
+            return false unless choice
+            return false unless choice.respond_to?(:value) && Array(choice.value).any?
+            return false if choice.respond_to?(:text) && Utils.present?(choice.text)
+
+            !present_children?(choice, %i[element ref data])
+          end
+
+          # True iff `choice` is a union: at least 2 <data> alternatives
+          # and no other content.
+          def pure_union_choice?(choice)
+            return false unless choice
+            return false unless choice.respond_to?(:data) && Array(choice.data).size >= 2
+
+            !present_children?(choice, %i[element ref value])
+          end
+
+          # Build a Definitions::Facet from an RNG <data>'s <param> children.
+          def facet_from_data(data)
+            facet = Definitions::Facet.new
+            Array(data.param).each do |param|
+              apply_param(facet, param.name, param.value.to_s)
+            end
+            facet
+          end
+
+          # Build a Definitions::Facet from an array of <value> elements.
+          def facet_from_values(values)
+            Definitions::Facet.new(
+              enumerations: Array(values).map(&:value),
+            )
+          end
+
+          # Snake_case symbol used as the registry key for a generated
+          # simple-type/union-type/namespace class.
+          def type_symbol(class_name)
+            Utils.snake_case(class_name).to_sym
+          end
+
+          # A class name derived from base_name that does not collide with an
+          # existing key in `classes` (appends 2, 3, ... on collision).
+          def unique_class_name(classes, base_name)
+            return base_name unless classes.key?(base_name)
+
+            counter = 2
+            counter += 1 while classes.key?("#{base_name}#{counter}")
+            "#{base_name}#{counter}"
+          end
+
+          # Maps an RNG/XSD base symbol to its Ruby parent class string,
+          # defaulting to the string type when unknown.
+          def parent_class_for(base_symbol)
+            Lutaml::Model::Type::TYPE_CODES.fetch(
+              base_symbol, Lutaml::Model::Type::TYPE_CODES[:string]
+            ).to_s
+          end
+
+          def apply_param(facet, name, value)
+            case name
+            when "minInclusive" then facet.min_inclusive = numeric_or_string(value)
+            when "maxInclusive" then facet.max_inclusive = numeric_or_string(value)
+            when "minExclusive" then facet.min_exclusive = numeric_or_string(value)
+            when "maxExclusive" then facet.max_exclusive = numeric_or_string(value)
+            when "minLength"    then facet.min_length = value.to_i
+            when "maxLength"    then facet.max_length = value.to_i
+            when "length"       then facet.length = value.to_i
+            when "pattern"      then facet.pattern = value
+            end
+          end
+
+          def numeric_or_string(value)
+            return value.to_i if /\A-?\d+\z/.match?(value)
+            return value.to_f if /\A-?\d+\.\d+\z/.match?(value)
+
+            value
+          end
+
+          STRUCTURAL_CHILD_NAMES = %i[
+            element ref attribute choice group
+            optional zeroOrMore oneOrMore
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/schema/rng_compiler/value_type_resolver.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Schema
+      module RngCompiler
+        # Resolves the value-shape of an element or attribute container into a
+        # Symbol (built-in / registered type) or nil if the container has
+        # structural content needing its own class.
+        #
+        # Patterns handled:
+        #   <element><text/></element>                              -> :string
+        #   <element><data type="X"/></element>                     -> mapped primitive
+        #   <element><data ...><param ...>/></data></element>       -> anonymous RestrictedType (returns its registry symbol)
+        #   <element><choice><value>...</value></choice></element>  -> anonymous RestrictedType (enum) (returns its registry symbol)
+        #   <element><ref name="StFoo"/></element>                  -> :st_foo (if simple)
+        #
+        # When an anonymous RestrictedType is needed, the resolver *builds* it
+        # (pure) and asks the supplied `register_class` callback to register
+        # it. Build and register are separate methods so unit testing can
+        # exercise the pure logic without side effects.
+        class ValueTypeResolver
+          def initialize(defines, classes, compile_define:, register_class:)
+            @defines = defines
+            @classes = classes
+            @compile_define = compile_define
+            @register_class = register_class
+          end
+
+          # Returns the resolved type symbol, or nil if `container` needs
+          # its own class. May register an anonymous RestrictedType as a
+          # side effect (delegated to the register_class callback).
+          def resolve(container)
+            return nil if RngHelpers.branching_structural?(container)
+
+            type_from_inline_simple(container) || primitive_or_ref(container)
+          end
+
+          private
+
+          def type_from_inline_simple(container)
+            simple = build_anonymous_simple_type(container)
+            return nil unless simple
+
+            @register_class.call(simple)
+            RngHelpers.type_symbol(simple.class_name)
+          end
+
+          def build_anonymous_simple_type(container)
+            anonymous_from_data(container) || anonymous_from_enum_choice(container)
+          end
+
+          def anonymous_from_data(container)
+            data = RngHelpers.single(container.data)
+            return nil unless data && Array(data.param).any?
+
+            base = RngCompiler::DATA_TYPE_MAP.fetch(
+              data.type, RngCompiler::DEFAULT_DATA_TYPE
+            )
+            anonymous_restricted_type(container, base, RngHelpers.facet_from_data(data))
+          end
+
+          def anonymous_from_enum_choice(container)
+            choice = RngHelpers.single(container.choice)
+            return nil unless choice && RngHelpers.pure_value_choice?(choice)
+
+            anonymous_restricted_type(container, :string, RngHelpers.facet_from_values(choice.value))
+          end
+
+          def anonymous_restricted_type(container, base, facet)
+            Definitions::RestrictedType.new(
+              class_name: RngHelpers.unique_class_name(
+                @classes, "#{Utils.camel_case(container.attr_name.to_s)}Type"
+              ),
+              parent_class: RngHelpers.parent_class_for(base),
+              facets: facet,
+            )
+          end
+
+          def primitive_or_ref(container)
+            primitive = detect_primitive_type(container)
+            return primitive if primitive
+
+            ref_to_simple_type_symbol(container)
+          end
+
+          def ref_to_simple_type_symbol(container)
+            ref = RngHelpers.single(container.ref)
+            return nil unless ref
+
+            target = @defines[ref.name]
+            return nil unless target
+
+            target_class = @compile_define.call(target)
+            return RngHelpers.type_symbol(target_class.class_name) if RngHelpers.simple_type?(target_class)
+
+            nil
+          end
+
+          def detect_primitive_type(child)
+            return nil if RngHelpers.structural_content?(child)
+
+            primitive_from_data(child) || primitive_from_text(child) || primitive_from_value(child)
+          end
+
+          def primitive_from_data(child)
+            return nil unless child.data
+
+            RngCompiler::DATA_TYPE_MAP.fetch(child.data.type, RngCompiler::DEFAULT_DATA_TYPE)
+          end
+
+          def primitive_from_text(child)
+            :string if Utils.present?(child.text)
+          end
+
+          def primitive_from_value(child)
+            # <element><choice><value>a</value>...</choice></element> falls
+            # through to this path as :string with no constraint emitted.
+            :string if Array(child.value).any?
+          end
+        end
+      end
+    end
+  end
+end