feat: report as a usage when no reference were found to manifest items

This PR introduces a new usage message (`OPF-097`) reported when the
manifest includes a resource for which no reference was found in content.

This is legit for instance for exempt resources (like data files included
in the container). But it is likely an author error otherwise, so reporting
a usage message can help to detect that.

We do not report an error since:
- references can be added via scripting, so the check can only be
  informative for scripted content
- EPUBCheck historically required all container resources to be listed
  in the manifest (not doing so was reported as a warning, `OPF-003`),
  which is conflicting with a requirement to **not** list unsused
  resources

Close #1452

src/main/java/com/adobe/epubcheck/messages/DefaultSeverities.java

@@ -291,6 +291,7 @@ private void initialize()
     severities.put(MessageId.OPF_095, Severity.ERROR);
     severities.put(MessageId.OPF_096, Severity.ERROR);
     severities.put(MessageId.OPF_096b, Severity.USAGE);
+    severities.put(MessageId.OPF_097, Severity.USAGE);
 
     // PKG
     severities.put(MessageId.PKG_001, Severity.WARNING);

src/main/java/com/adobe/epubcheck/messages/MessageId.java

@@ -285,6 +285,7 @@ public enum MessageId implements Comparable<MessageId>
   OPF_095("OPF-095"),
   OPF_096("OPF-096"),
   OPF_096b("OPF-096b"),
+  OPF_097("OPF-097"),
 
   // Messages relating to the entire package
   PKG_001("PKG-001"),

src/main/java/com/adobe/epubcheck/opf/OPFChecker30.java

@@ -122,6 +122,17 @@ protected void checkItem(OPFItem item, OPFHandler opfHandler)
     {
       report.message(MessageId.OPF_091, item.getLocation());
     }
+
+    // Register media overlay usage
+    if (context.referenceRegistry.isPresent() && !Strings.isNullOrEmpty(item.getMediaOverlay()))
+    {
+      Optional<OPFItem> overlay = opfHandler.getItemById(item.getMediaOverlay());
+      if (overlay.isPresent())
+      {
+        context.referenceRegistry.get().registerReference(overlay.get().getURL(),
+            Reference.Type.MEDIA_OVERLAY, item.getLocation());
+      }
+    }
   }
 
   @Override
@@ -156,6 +167,18 @@ else if (!context.referenceRegistry.get().hasReferencesTo(item.getURL()))
       }
     }
 
+    // check that resources in the manifest are referenced (usage report)
+    // - search the reference registry
+    // - report if no reference (of a publication-resource type) is found
+    if (!(item.isInSpine() || item.isNav() || item.isNcx())
+        && context.referenceRegistry.isPresent()
+        && context.referenceRegistry.get().asList().stream()
+            .noneMatch(ref -> ref.targetResource.equals(item.getURL())
+                && ref.type.isPublicationResourceReference()))
+    {
+      report.message(MessageId.OPF_097, item.getLocation(), item.getPath());
+    }
+
     if (isBlessedItemType(mediatype, version))
     {
       // check whether media-overlay attribute needs to be specified

src/main/java/org/w3c/epubcheck/core/references/Reference.java

@@ -15,6 +15,7 @@ public static enum Type
     // Publication resources
     GENERIC,
     STYLESHEET,
+    MEDIA_OVERLAY,
     HYPERLINK,
     FONT,
     IMAGE,
@@ -30,7 +31,25 @@ public static enum Type
     SEARCH_KEY,
     NAV_TOC_LINK,
     NAV_PAGELIST_LINK,
-    OVERLAY_TEXT_LINK,
+    OVERLAY_TEXT_LINK;
+
+    public boolean isPublicationResourceReference()
+    {
+      switch (this)
+      {
+      case GENERIC:
+      case STYLESHEET:
+      case FONT:
+      case IMAGE:
+      case AUDIO:
+      case VIDEO:
+      case TRACK:
+      case MEDIA_OVERLAY:
+        return true;
+      default:
+        return false;
+      }
+    }
   }
 
   public final URL url;

src/main/resources/com/adobe/epubcheck/messages/MessageBundle.properties

@@ -212,7 +212,8 @@ OPF_093=The "media-type" attribute is required for linked resources located in t
 OPF_094=The "media-type" attribute is required for "%1$s" links.
 OPF_095=The "media-type" attribute of "voicing" links must be an audio MIME type, but found "%1$s".
 OPF_096=Non-linear content must be reachable, but found no hyperlink to "%1$s".
-OPF_096b=No hyperlink was found to non-linear document "%1$s", please check that it can be reached from scripted content.  
+OPF_096b=No hyperlink was found to non-linear document "%1$s", please check that it can be reached from scripted content.
+OPF_097=Resource "%1$s" is listed in the manifest, but no reference to it was found in content documents. 
 
 #Package
 PKG_001=Validating the EPUB against version %1$s but detected version %2$s.

src/test/resources/com/adobe/epubcheck/tools/20-severity-tester/OPS/toc.ncx

@@ -12,7 +12,7 @@
       <navLabel>
         <text>Loomings</text>
       </navLabel>
-      <content src="content_001.xhtml"/>
+      <content src="content%20001.xhtml"/>
     </navPoint>
   </navMap>
 </ncx>

src/test/resources/com/adobe/epubcheck/tools/20-warning-tester/OPS/package.opf

@@ -6,7 +6,7 @@
   <dc:identifier id="q">NOID</dc:identifier>
 </metadata>
 <manifest>
-  <item id="content_001"  href="content_001.xhtml" media-type="application/xhtml+xml"/>
+  <item id="content_001"  href="content%20001.xhtml" media-type="application/xhtml+xml"/>
   <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml" />
 </manifest>
 <spine toc="ncx">

src/test/resources/com/adobe/epubcheck/tools/20-warning-tester/OPS/toc.ncx

@@ -11,7 +11,7 @@
       <navLabel>
         <text>Loomings</text>
       </navLabel>
-      <content src="content_001.xhtml"/>
+      <content src="content%20001.xhtml"/>
     </navPoint>
   </navMap>
 </ncx>

src/test/resources/com/adobe/epubcheck/tools/severity_override.txt

@@ -1,4 +1,5 @@
 ID	Severity	Message	Suggestion
 RSC-008	ERROR	This is an overridden message	This is an overridden suggestion.
+PKG-010	ERROR
 OPF-003	ERROR
 NCX-004	SUPPRESSED

src/test/resources/epub3/09-media-overlays/files/mediaoverlays-active-class-stylesheet-undeclared-valid/EPUB/content_001.xhtml

@@ -3,6 +3,7 @@
 	<head>
 		<meta charset="utf-8" />
 		<title>Minimal EPUB</title>
+		<link rel="stylesheet" href="styles.css"/>
 	</head>
 	<body>
 		<h1 id="c01">Loomings</h1>