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>