rng 0.3.7 → 0.3.8

data/lib/rng/rnc_to_rng_converter.rb

@@ -17,6 +17,8 @@ module Rng
   #   grammar = Rng::Grammar.from_xml(rng_xml)
   class RncToRngConverter
     RNG_NAMESPACE = 'http://relaxng.org/ns/structure/1.0'
+    OCCURRENCE_TAGS = { '*' => 'zeroOrMore', '+' => 'oneOrMore', '?' => 'optional' }.freeze
+    private_constant :OCCURRENCE_TAGS
 
     # Convert a parse tree to RNG XML
     #
@@ -60,41 +62,11 @@ module Rng
             xml.parent[:datatypeLibrary] = tree[:datatype_map].values.first
           end
 
-          # If no explicit start but we have top-level elements, wrap them in start
-          has_explicit_start = tree[:start] && tree[:start][:start_pattern]
-          has_top_elements = tree[:definitions]&.any? do |d|
-            d.key?(:top_element)
-          end
-          has_top_choice = tree[:definitions]&.any? do |d|
-            d.key?(:top_choice)
-          end
-
-          if has_explicit_start
-            # Process explicit start pattern
-            xml.start do
-              add_documentation(xml, tree[:start]) if tree[:start][:docs]
-              process_pattern_list(xml, tree[:start][:start_pattern])
-            end
-          elsif has_top_choice
-            # No explicit start, but has top-level choice - wrap in start with choice
-            first_choice = tree[:definitions].find { |d| d.key?(:top_choice) }
-            xml.start do
-              xml.choice do
-                process_content_item(xml, first_choice[:top_choice][:first])
-                first_choice[:top_choice][:choice_items]&.each do |item|
-                  process_content_item(xml, item)
-                end
-              end
-            end
-          elsif has_top_elements
-            # No explicit start, but has top-level elements - wrap first one in start
-            xml.start do
-              first_element = tree[:definitions].find do |d|
-                d.key?(:top_element)
-              end
-              process_content_item(xml, first_element[:top_element])
-            end
-          end
+          # A leading `start` (tree[:start]) or a non-leading one (emitted as
+          # <start> in the definitions loop) both suppress auto-wrapping.
+          has_explicit_start =
+            (tree[:start] && tree[:start][:start_pattern]) || nonleading_start?(tree)
+          emit_grammar_start(xml, tree)
 
           # Process named patterns and remaining top-level elements
           tree[:definitions]&.each_with_index do |def_item, idx|
@@ -162,6 +134,8 @@ module Rng
                 # Include without override block
                 xml.include(href: href)
               end
+            elsif def_item.key?(:name) && keyword_start_name?(def_item[:name])
+              emit_nonleading_start(xml, def_item)
             elsif def_item.key?(:name)
               # Named pattern - handle augmentation operators
               name = process_identifier(def_item[:name])
@@ -440,6 +414,66 @@ module Rng
       end
     end
 
+    # Emit the grammar's <start>: an explicit leading start, or (when there is
+    # none) auto-wrap the first top-level choice/element. A non-leading start is
+    # emitted by the definitions loop, so here it only suppresses auto-wrapping.
+    def emit_grammar_start(xml, tree)
+      if tree[:start] && tree[:start][:start_pattern]
+        xml.start do
+          add_documentation(xml, tree[:start]) if tree[:start][:docs]
+          process_pattern_list(xml, tree[:start][:start_pattern])
+        end
+      elsif nonleading_start?(tree)
+        # Emitted as <start> by the definitions loop.
+      elsif (choice = tree[:definitions]&.find { |d| d.key?(:top_choice) })
+        emit_start_from_top_choice(xml, choice)
+      elsif (element = tree[:definitions]&.find { |d| d.key?(:top_element) })
+        xml.start { process_content_item(xml, element[:top_element]) }
+      end
+    end
+
+    def emit_start_from_top_choice(xml, first_choice)
+      xml.start do
+        xml.choice do
+          process_content_item(xml, first_choice[:top_choice][:first])
+          first_choice[:top_choice][:choice_items]&.each do |item|
+            process_content_item(xml, item)
+          end
+        end
+      end
+    end
+
+    # True when a `start = X` / `start |= X` appears outside the leading
+    # position and was parsed as a named pattern named "start".
+    def nonleading_start?(tree)
+      tree[:definitions]&.any? do |d|
+        d.key?(:name) && keyword_start_name?(d[:name])
+      end || false
+    end
+
+    # True when a named-pattern name is the `start` keyword, and NOT an escaped
+    # identifier `\start` (a define literally named "start", which must stay a
+    # <define>). The escape survives as a backslash_escape identifier part.
+    def keyword_start_name?(name_node)
+      process_identifier(name_node) == 'start' && !escaped_identifier?(name_node)
+    end
+
+    def escaped_identifier?(name_node)
+      parts = name_node.is_a?(Hash) ? name_node[:identifier_parts] : nil
+      Array(parts).any? { |p| p.is_a?(Hash) && p.key?(:backslash_escape) }
+    end
+
+    # Emit a real <start> for a non-leading `start = X` / `start |= X` that was
+    # parsed as a named pattern (a <define name="start"> would be wrong).
+    def emit_nonleading_start(xml, def_item)
+      op = def_item[:operator] ? extract_string(def_item[:operator]) : '='
+      combine = { '|=' => 'choice', '&=' => 'interleave' }[op]
+      xml.start(combine ? { combine: combine } : {}) do
+        add_documentation(xml, def_item) if def_item[:docs]
+        process_pattern_list(xml, def_item[:pattern])
+      end
+    end
+
     # Collect prefixed namespace declarations from preamble items
     def collect_namespace_prefixes(preamble_items)
       return unless preamble_items
@@ -722,6 +756,13 @@ module Rng
       end
     end
 
+    def wrap_with_occurrence(xml, occurrence, &block)
+      tag = OCCURRENCE_TAGS[occurrence.to_s] if occurrence
+      return yield unless tag
+
+      xml.send(tag, &block)
+    end
+
     def process_content_item(xml, item)
       if item.key?(:type) && item.key?(:name)
         # Attribute definition (has both :type and :name keys)
@@ -821,19 +862,7 @@ module Rng
           end
         end
 
-        if occurrence
-          # Wrap in occurrence element
-          occurrence_tag = case occurrence.to_s
-                           when '*' then 'zeroOrMore'
-                           when '+' then 'oneOrMore'
-                           when '?' then 'optional'
-                           end
-          xml.send(occurrence_tag) do
-            attribute_block.call(xml)
-          end
-        else
-          attribute_block.call(xml)
-        end
+        wrap_with_occurrence(xml, occurrence) { attribute_block.call(xml) }
       elsif item.key?(:name)
         # Element definition
         attrs = {}
@@ -939,26 +968,19 @@ module Rng
           end
         end
 
-        if occurrence
-          # Wrap in occurrence element
-          occurrence_tag = case occurrence.to_s
-                           when '*' then 'zeroOrMore'
-                           when '+' then 'oneOrMore'
-                           when '?' then 'optional'
-                           end
-
-          xml.send(occurrence_tag) do
-            element_block.call(xml)
-          end
-        else
-          element_block.call(xml)
-        end
+        wrap_with_occurrence(xml, occurrence) { element_block.call(xml) }
       elsif item.key?(:text)
-        xml.parent << Nokogiri::XML::Node.new('text', xml.doc)
+        wrap_with_occurrence(xml, item[:occurrence]) do
+          xml.parent << Nokogiri::XML::Node.new('text', xml.doc)
+        end
       elsif item.key?(:empty)
-        xml.parent << Nokogiri::XML::Node.new('empty', xml.doc)
+        wrap_with_occurrence(xml, item[:occurrence]) do
+          xml.parent << Nokogiri::XML::Node.new('empty', xml.doc)
+        end
       elsif item.key?(:not_allowed)
-        xml.parent << Nokogiri::XML::Node.new('notAllowed', xml.doc)
+        wrap_with_occurrence(xml, item[:occurrence]) do
+          xml.parent << Nokogiri::XML::Node.new('notAllowed', xml.doc)
+        end
       elsif item.key?(:list_content)
         xml.list do
           process_list_content(xml, item[:list_content])
@@ -968,21 +990,7 @@ module Rng
       elsif item.key?(:external_href)
         xml.externalRef(href: process_string_literal(item[:external_href]))
       elsif item.key?(:group)
-        occurrence = item[:occurrence]
-
-        if occurrence
-          occurrence_tag = case occurrence.to_s
-                           when '*' then 'zeroOrMore'
-                           when '+' then 'oneOrMore'
-                           when '?' then 'optional'
-                           end
-
-          xml.send(occurrence_tag) do
-            xml.group do
-              process_element_content(xml, item[:group])
-            end
-          end
-        else
+        wrap_with_occurrence(xml, item[:occurrence]) do
           xml.group do
             process_element_content(xml, item[:group])
           end
@@ -997,28 +1005,34 @@ module Rng
         ref_name = process_identifier(item[:ref])
         raise StandardError, "subtraction operator '-' cannot be used as a pattern" if ref_name == '-'
 
-        xml.ref(name: ref_name)
+        wrap_with_occurrence(xml, item[:occurrence]) do
+          xml.ref(name: ref_name)
+        end
       elsif item.key?(:prefix) && item.key?(:type)
         # Datatype reference (e.g., xsd:string { maxLength = "100" })
         data_attrs = {
           type: process_identifier(item[:type]),
           datatypeLibrary: 'http://www.w3.org/2001/XMLSchema-datatypes'
         }
-        if item[:params]
-          xml.data(data_attrs) do
-            params = item[:params].is_a?(Array) ? item[:params] : [item[:params]]
-            params.each do |param|
-              param_name = process_identifier(param[:param_name])
-              param_value = process_string_literal(param[:param_value])
-              xml.param(param_value, name: param_name)
+        wrap_with_occurrence(xml, item[:occurrence]) do
+          if item[:params]
+            xml.data(data_attrs) do
+              params = item[:params].is_a?(Array) ? item[:params] : [item[:params]]
+              params.each do |param|
+                param_name = process_identifier(param[:param_name])
+                param_value = process_string_literal(param[:param_value])
+                xml.param(param_value, name: param_name)
+              end
             end
+          else
+            xml.data(data_attrs)
           end
-        else
-          xml.data(data_attrs)
         end
       elsif item.key?(:value)
         # Value literal (string) in element content
-        xml.value(process_string_literal(item[:value]))
+        wrap_with_occurrence(xml, item[:occurrence]) do
+          xml.value(process_string_literal(item[:value]))
+        end
       elsif item.key?(:grammar_block)
         # Inline grammar block
         grammar_data = item[:grammar_block]
@@ -1158,8 +1172,6 @@ module Rng
 
     # Process a single list content item (datatype or text with optional occurrence)
     def process_list_item(xml, item)
-      occurrence = item[:occurrence]&.to_s
-
       item_block = lambda do |xml_ctx|
         if item.key?(:text)
           xml_ctx.parent << Nokogiri::XML::Node.new('text', xml_ctx.doc)
@@ -1179,18 +1191,7 @@ module Rng
         end
       end
 
-      if occurrence
-        occurrence_tag = case occurrence
-                         when '*' then 'zeroOrMore'
-                         when '+' then 'oneOrMore'
-                         when '?' then 'optional'
-                         end
-        xml.send(occurrence_tag) do
-          item_block.call(xml)
-        end
-      else
-        item_block.call(xml)
-      end
+      wrap_with_occurrence(xml, item[:occurrence]) { item_block.call(xml) }
     end
 
     # Process name except clause for wildcards
@@ -1243,18 +1244,17 @@ module Rng
 
     # Process attribute type content (factored out for wildcard support)
     def process_attribute_type(xml, type_info)
-      if type_info == 'text' || (type_info.is_a?(Hash) && type_info.key?(:text_type))
-        xml.parent << Nokogiri::XML::Node.new('text', xml.doc)
-      elsif type_info.is_a?(Hash) && type_info.key?(:value_choice)
-        # Choice of value literals
+      if type_info.is_a?(Hash) && type_info.key?(:attribute_choice)
+        # Choice of attribute items (text / value literals / refs)
         xml.choice do
-          # First value (before the choice operator)
-          xml.value(process_string_literal(type_info[:value]))
-          # Remaining values (after | operators)
-          type_info[:value_choice].each do |val|
-            xml.value(process_string_literal(val[:value]))
+          # The first item is hoisted alongside the rest of the choice
+          emit_attribute_choice_item(xml, type_info)
+          type_info[:attribute_choice].each do |item|
+            emit_attribute_choice_item(xml, item)
           end
         end
+      elsif type_info == 'text' || (type_info.is_a?(Hash) && type_info.key?(:text_type))
+        xml.parent << Nokogiri::XML::Node.new('text', xml.doc)
       elsif type_info.is_a?(Hash) && type_info.key?(:value)
         # Single value literal
         xml.value(process_string_literal(type_info[:value]))
@@ -1282,6 +1282,16 @@ module Rng
       end
     end
 
+    def emit_attribute_choice_item(xml, item)
+      if item.key?(:text_type)
+        xml.parent << Nokogiri::XML::Node.new('text', xml.doc)
+      elsif item.key?(:value)
+        xml.value(process_string_literal(item[:value]))
+      elsif item.key?(:ref)
+        xml.ref(name: process_identifier(item[:ref]))
+      end
+    end
+
     # Process data parameters (e.g., maxLength = "100")
     def process_data_params(xml, params)
       params = [params] unless params.is_a?(Array)

data/lib/rng/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rng
-  VERSION = '0.3.7'
+  VERSION = '0.3.8'
 end

data/lib/rng.rb

@@ -39,7 +39,6 @@ module Rng
   autoload :Grammar, File.expand_path('rng/grammar', __dir__)
   autoload :Documentation, File.expand_path('rng/documentation', __dir__)
   autoload :TestSuiteParser, File.expand_path('rng/test_suite_parser', __dir__)
-  autoload :Value, File.expand_path('rng/value', __dir__)
 
   # Autoload parser support classes
   autoload :ParseTreeProcessor, File.expand_path('rng/parse_tree_processor', __dir__)
@@ -57,7 +56,6 @@ module Rng
 
   # Autoload parsers and builders
   autoload :RncParser, File.expand_path('rng/rnc_parser', __dir__)
-  autoload :ParseRnc, File.expand_path('rng/parse_rnc', __dir__)
   autoload :ToRnc, File.expand_path('rng/to_rnc', __dir__)
   autoload :RncBuilder, File.expand_path('rng/rnc_builder', __dir__)
   autoload :IncludeProcessor, File.expand_path('rng/include_processor', __dir__)
@@ -67,13 +65,17 @@ module Rng
   def parse(rng, location: nil, nested_schema: false, validate: false, resolve_external: false)
     SchemaValidator.validate(rng) if validate && !nested_schema
     grammar = Grammar.from_xml(rng)
-    return grammar unless resolve_external
+
+    unless resolve_external
+      grammar.warnings = ExternalRefResolver.unresolved_ref_hrefs(grammar)
+      return grammar
+    end
 
     ExternalRefResolver.new(grammar, location: location).resolve
   end
 
-  def self.parse_rnc(rnc)
-    ParseRnc.parse(rnc)
+  def self.parse_rnc(rnc, location: nil)
+    IncludeProcessor.new.parse_content(rnc, location: location)
   end
 
   def self.parse_file(file_path)

data/rng.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'lutaml-model', '~> 0.8.0'
+  spec.add_dependency 'lutaml-model', '~> 0.8.114'
   spec.add_dependency 'nokogiri'
   spec.add_dependency 'parslet'
 

data/spec/fixtures/external/order_lib.rng

@@ -0,0 +1,13 @@
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+  <start>
+    <element name="root">
+      <element name="first">
+        <empty/>
+      </element>
+      <attribute name="mid"/>
+      <element name="last">
+        <empty/>
+      </element>
+    </element>
+  </start>
+</grammar>

data/spec/fixtures/external/order_main.rng

@@ -0,0 +1,3 @@
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+  <include href="order_lib.rng"/>
+</grammar>

data/spec/rng/advanced_rnc_spec.rb

@@ -2,6 +2,7 @@
 
 require 'spec_helper'
 require 'rng'
+require 'parslet'
 
 RSpec.describe 'Advanced RNC features' do
   describe 'Name wildcards' do
@@ -98,4 +99,126 @@ RSpec.describe 'Advanced RNC features' do
       expect { Rng.parse_rnc(rnc) }.not_to raise_error
     end
   end
+
+  describe 'Content-position annotations' do
+    it 'parses a bracket annotation before an attribute in content' do
+      rnc = 'start = element n { [ a:defaultValue = "x" ] attribute foo { text } }'
+      expect { Rng.parse_rnc(rnc) }.not_to raise_error
+    end
+
+    it 'parses a bracket annotation before a nested element in content' do
+      rnc = 'start = element n { [ a:documentation [ "hi" ] ] element c { text } }'
+      expect { Rng.parse_rnc(rnc) }.not_to raise_error
+    end
+
+    it 'parses an annotated attribute within a sequence' do
+      rnc = 'start = element n { [ a:x = "1" ] attribute foo { text }, ' \
+            'attribute bar { text } }'
+      grammar = Rng.parse_rnc(rnc)
+      attrs = grammar.start.first.element.attribute.map(&:attr_name)
+      expect(attrs).to eq(%w[foo bar])
+    end
+
+    it 'leaves un-annotated content parsing unchanged' do
+      rnc = 'start = element n { attribute foo { text } }'
+      expect { Rng.parse_rnc(rnc) }.not_to raise_error
+    end
+
+    it 'does not let brackets inside an annotation string close it early' do
+      rnc = 'start = element n { [ a:x = "a]b[c" ] attribute foo { text }, ' \
+            'attribute bar { text } }'
+      grammar = Rng.parse_rnc(rnc)
+      attrs = grammar.start.first.element.attribute.map(&:attr_name)
+      expect(attrs).to eq(%w[foo bar])
+    end
+
+    it 'ignores brackets inside a single-quoted annotation string' do
+      rnc = "start = element n { [ a:x = 'a]b[c' ] attribute foo { text }, " \
+            'attribute bar { text } }'
+      grammar = Rng.parse_rnc(rnc)
+      attrs = grammar.start.first.element.attribute.map(&:attr_name)
+      expect(attrs).to eq(%w[foo bar])
+    end
+
+    it 'ignores brackets inside a triple-quoted annotation string' do
+      rnc = 'start = element n { [ a:doc [ """multi]line[x""" ] ] ' \
+            'attribute foo { text }, attribute bar { text } }'
+      grammar = Rng.parse_rnc(rnc)
+      attrs = grammar.start.first.element.attribute.map(&:attr_name)
+      expect(attrs).to eq(%w[foo bar])
+    end
+
+    it 'drops an annotation before a non-leading definition without corrupting it' do
+      rnc = "foo = element foo { text }\n" \
+            "[ a:defaultValue = \"x\" ]\n" \
+            "bar = element bar { text }\n" \
+            'start = foo'
+      grammar = Rng.parse_rnc(rnc)
+
+      expect(grammar.define.map(&:name)).to contain_exactly('foo', 'bar')
+    end
+
+    it 'rejects a control character inside an annotation string, like a value string' do
+      rnc = "start = element n { [ a:x = \"#{1.chr}\" ] " \
+            'attribute foo { text } }'
+      expect { Rng.parse_rnc(rnc) }.to raise_error(Parslet::ParseFailed)
+    end
+  end
+
+  describe 'Sequence separators' do
+    it 'rejects comma-less sequence items so they cannot swallow the next definition' do
+      rnc = 'start = element n { attribute foo { text } attribute bar { text } }'
+      expect { Rng.parse_rnc(rnc) }.to raise_error(Parslet::ParseFailed)
+    end
+
+    it 'parses comma-separated sequence items in element content' do
+      rnc = 'start = element n { attribute foo { text }, attribute bar { text } }'
+      grammar = Rng.parse_rnc(rnc)
+      attrs = grammar.start.first.element.attribute.map(&:attr_name)
+      expect(attrs).to eq(%w[foo bar])
+    end
+  end
+
+  describe 'Non-leading start' do
+    it 'produces a real <start> for a start = element after other defines' do
+      rnc = "item = element item { text }\nstart = element root { item* }"
+      grammar = Rng.parse_rnc(rnc)
+
+      expect(grammar.start.first.element.attr_name).to eq('root')
+      expect(grammar.define.map(&:name)).to eq(['item'])
+    end
+
+    it 'produces a real <start> for a non-leading start = ref' do
+      rnc = "library = element library { text }\nstart = library"
+      grammar = Rng.parse_rnc(rnc)
+
+      expect(grammar.start.first.ref.name).to eq('library')
+      expect(grammar.define.map(&:name)).not_to include('start')
+    end
+
+    it 'collects multiple start |= definitions as combining starts' do
+      rnc = "a = element a { empty }\nb = element b { empty }\n" \
+            "start |= a\nstart |= b"
+      grammar = Rng.parse_rnc(rnc)
+
+      expect(grammar.start.map(&:combine)).to eq(%w[choice choice])
+      expect(grammar.start.map { |s| s.ref.name }).to contain_exactly('a', 'b')
+    end
+
+    it 'maps start &= to interleave-combining starts' do
+      rnc = "a = element a { empty }\nb = element b { empty }\n" \
+            "start &= a\nstart &= b"
+      grammar = Rng.parse_rnc(rnc)
+
+      expect(grammar.start.map(&:combine)).to eq(%w[interleave interleave])
+    end
+
+    it 'keeps an escaped \\start as a define, not the grammar start' do
+      rnc = "x = element x { text }\n\\start = element a { text }\nstart = x"
+      grammar = Rng.parse_rnc(rnc)
+
+      expect(grammar.define.map(&:name)).to include('start')
+      expect(grammar.start.first.ref.name).to eq('x')
+    end
+  end
 end

data/spec/rng/external_ref_resolver_spec.rb

@@ -69,6 +69,22 @@ RSpec.describe Rng::ExternalRefResolver do
       end
     end
 
+    context 'with interleaved children reached through an include' do
+      let(:order_main) { File.read('spec/fixtures/external/order_main.rng') }
+
+      it 'preserves element_order through external ref resolution' do
+        grammar = Rng::Grammar.from_xml(order_main)
+        resolved = described_class.new(grammar, location: 'spec/fixtures/external/order_main.rng').resolve
+
+        xml = resolved.to_xml
+        expect(xml.index('first')).to be < xml.index('mid')
+        expect(xml.index('mid')).to be < xml.index('last')
+
+        root = resolved.start.first.element
+        expect(root.instance_variable_get(:@element_order)).not_to be_nil
+      end
+    end
+
     context 'with non-existent external file' do
       it 'does not raise error but warns when external file not found' do
         # Create a grammar with a non-existent include
@@ -110,6 +126,13 @@ RSpec.describe Rng::ExternalRefResolver do
       # Without resolve_external, the grammar is returned as-is
       expect(grammar).to be_a(Rng::Grammar)
     end
+
+    it 'warns about unresolved external references when not resolving' do
+      main_rng = File.read('spec/fixtures/external/include_main.rng')
+      grammar = Rng.parse(main_rng)
+
+      expect(grammar.warnings).to include(a_string_matching(/include_lib\.rng/))
+    end
   end
 
   describe Rng::ExternalRefResolver::ExternalRefResolutionError do

data/spec/rng/parse_rnc_spec.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'tmpdir'
+
+RSpec.describe 'ParseRncSpec' do
+  describe '.parse_rnc' do
+    let(:simple_rnc) { 'element foo { text }' }
+
+    it 'returns a Grammar for include-free RNC without a location' do
+      parsed = Rng.parse_rnc(simple_rnc)
+
+      expect(parsed).to be_a(Rng::Grammar)
+      expect(parsed.start.first.element.attr_name).to eq('foo')
+    end
+
+    it 'produces equivalent output with and without location for hex-escaped RNC' do
+      # \x{72}oot decodes to "root". Hex preprocessing must run on the
+      # with-location path or the parse tree differs from the no-location path
+      # for the same input — which is the divergence this spec guards against.
+      rnc = 'element \\x{72}oot { text }'
+
+      Dir.mktmpdir do |dir|
+        scratch = File.join(dir, 'scratch.rnc')
+
+        without_location = Rng.parse_rnc(rnc)
+        with_location = Rng.parse_rnc(rnc, location: scratch)
+
+        expect(with_location.to_xml).to be_xml_equivalent_to(without_location.to_xml)
+        expect(with_location.start.first.element.attr_name).to eq('root')
+      end
+    end
+
+    it 'resolves relative includes when location is the source directory' do
+      Dir.mktmpdir do |dir|
+        File.write(File.join(dir, 'child.rnc'), <<~RNC)
+          ChildPattern = element child { text }
+          start = element wrapped { ChildPattern }
+        RNC
+
+        parent_path = File.join(dir, 'parent.rnc')
+        File.write(parent_path, <<~RNC)
+          include "child.rnc" {
+            start = element root { ChildPattern }
+          }
+        RNC
+
+        parsed = Rng.parse_rnc(File.read(parent_path), location: dir)
+
+        expect(parsed.define.map(&:name)).to include('ChildPattern')
+        expect(parsed.start.first.element.attr_name).to eq('root')
+      end
+    end
+
+    it 'also accepts a source file path as location' do
+      Dir.mktmpdir do |dir|
+        File.write(File.join(dir, 'child.rnc'), <<~RNC)
+          ChildPattern = element child { text }
+        RNC
+
+        parent_path = File.join(dir, 'parent.rnc')
+        File.write(parent_path, <<~RNC)
+          include "child.rnc" {
+            start = element root { ChildPattern }
+          }
+        RNC
+
+        parsed = Rng.parse_rnc(File.read(parent_path), location: parent_path)
+
+        expect(parsed.define.map(&:name)).to include('ChildPattern')
+        expect(parsed.start.first.element.attr_name).to eq('root')
+      end
+    end
+  end
+end