feat: update checking of the Package Document 'refines' attribute

- `refines` MUST be a relative URL
- `refines` SHOULD refer to a Publication Resource by ID
- `refines` MUST point to an existing ID when it is a fragment-only URL

Fix #1226

src/main/resources/com/adobe/epubcheck/schema/30/package-30.sch

@@ -51,7 +51,22 @@
     <!-- Metadata checks -->
 
     <pattern id="opf.refines.relative">
-        <rule context="*[@refines and starts-with(normalize-space(@refines),'#')][not(ancestor::opf:collection)]">
+        <rule context="*[not(ancestor::opf:collection)][@refines]">
+            <report test="matches(@refines,'[a-zA-Z]([a-zA-Z0-9]|\+|\-|\.)*:')">@refines must be a relative URL</report>
+        </rule>
+    </pattern>
+    <pattern id="opf.refines.by-fragment">
+        <rule context="*[not(ancestor::opf:collection)][@refines]">
+            <let name="refines-url" value="resolve-uri(@refines)"/>
+            <let name="item" value="//opf:manifest/opf:item[resolve-uri(normalize-space(@href))=$refines-url]"/>
+            <report test="$item">WARNING: @refines should instead refer to "<value-of
+                select="@refines"/>" using a fragment identifier pointing to its manifest item ("#<value-of
+                    select="$item/@id"/>")
+            </report>
+        </rule>
+    </pattern>
+    <pattern id="opf.refines.fragment-exists">
+        <rule context="*[not(ancestor::opf:collection)][@refines and starts-with(normalize-space(@refines),'#')]">
         	<let name="refines-target-id" value="substring(normalize-space(@refines), 2)"/>
             <assert test="//*[normalize-space(@id)=$refines-target-id]">@refines missing target id: "<value-of
                     select="$refines-target-id"/>"</assert>

src/test/resources/epub3/files/package-document/metadata-refines-not-a-fragment-warning.opf

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="uid"
+  xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <metadata>
+    <dc:title>Title</dc:title>
+    <dc:language>en</dc:language>
+    <dc:identifier id="uid">NOID</dc:identifier>
+    <meta property="dcterms:modified">2019-01-01T12:00:00Z</meta>
+    <meta property="media:duration">10min</meta>
+    <meta refines="mediaoverlay_001.smil" property="media:duration">10min</meta>
+  </metadata>
+  <manifest>
+    <item id="t001" href="contents.xhtml" properties="nav" media-type="application/xhtml+xml"/>
+    <item id="mo001" href="mediaoverlay_001.smil" media-type="application/smil+xml"/>
+  </manifest>
+  <spine>
+    <itemref idref="t001"/>
+  </spine>
+</package>

src/test/resources/epub3/files/package-document/metadata-refines-not-relative-error.opf

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="uid"
+  xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <metadata>
+    <dc:title>Title</dc:title>
+    <dc:language>en</dc:language>
+    <dc:identifier id="uid">NOID</dc:identifier>
+    <meta property="dcterms:modified">2019-01-01T12:00:00Z</meta>
+    <meta property="media:duration">10min</meta>
+    <meta refines="https://example.org/mediaoverlay_001.smil" property="media:duration">10min</meta>
+  </metadata>
+  <manifest>
+    <item id="t001" href="contents.xhtml" properties="nav" media-type="application/xhtml+xml"/>
+    <item id="mo001" href="mediaoverlay_001.smil" media-type="application/smil+xml"/>
+  </manifest>
+  <spine>
+    <itemref idref="t001"/>
+  </spine>
+</package>

src/test/resources/epub3/package-document.feature

@@ -192,7 +192,19 @@ Feature: EPUB 3 ▸ Packages ▸ Package Document Checks
     And the message contains "must be a string with length at least 1" 
     And no other errors or warnings are reported
 
-  Scenario: 'refines' attribute must target an existing ID
+  Scenario: 'refines' attribute MUST be a relative URL 
+    When checking file 'metadata-refines-not-relative-error.opf'
+    Then error RSC-005 is reported
+    And the message contains "@refines must be a relative URL"
+    And no other errors or warnings are reported
+
+  Scenario: 'refines' attribute should use a fragment ID if refering to a Publication Resource 
+    When checking file 'metadata-refines-not-a-fragment-warning.opf'
+    Then warning RSC-017 is reported
+    And the message contains "using a fragment identifier pointing to its manifest item"
+    And no other errors or warnings are reported
+
+  Scenario: 'refines' attribute, when using fragment ID, must target an existing ID
     When checking file 'metadata-refines-unknown-id-error.opf'
     Then error RSC-005 is reported
     And the message contains "@refines missing target id"