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

rdeltour · rdeltour · commit 09244a493f70 · 2022-12-23T18:18:47.000+01:00
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
diff --git a/src/main/java/com/adobe/epubcheck/messages/DefaultSeverities.java b/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);
diff --git a/src/main/java/com/adobe/epubcheck/messages/MessageId.java b/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"),
diff --git a/src/main/java/com/adobe/epubcheck/opf/OPFChecker30.java b/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
diff --git a/src/main/java/org/w3c/epubcheck/core/references/Reference.java b/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;
diff --git a/src/main/resources/com/adobe/epubcheck/messages/MessageBundle.properties b/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.
diff --git a/src/test/resources/com/adobe/epubcheck/tools/20-severity-tester/OPS/content 001.xhtml b/src/test/resources/com/adobe/epubcheck/tools/20-severity-tester/OPS/content 001.xhtml
diff --git a/src/test/resources/com/adobe/epubcheck/tools/20-severity-tester/OPS/toc.ncx b/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>
diff --git a/src/test/resources/com/adobe/epubcheck/tools/20-warning-tester/OPS/content 001.xhtml b/src/test/resources/com/adobe/epubcheck/tools/20-warning-tester/OPS/content 001.xhtml
diff --git a/src/test/resources/com/adobe/epubcheck/tools/20-warning-tester/OPS/content_002.xhtml b/src/test/resources/com/adobe/epubcheck/tools/20-warning-tester/OPS/content_002.xhtml
diff --git a/src/test/resources/com/adobe/epubcheck/tools/20-warning-tester/OPS/package.opf b/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">
diff --git a/src/test/resources/com/adobe/epubcheck/tools/20-warning-tester/OPS/toc.ncx b/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>
diff --git a/src/test/resources/com/adobe/epubcheck/tools/severity_override.txt b/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
diff --git a/src/test/resources/epub3/09-media-overlays/files/mediaoverlays-active-class-stylesheet-undeclared-valid/EPUB/content_001.xhtml b/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>

Original file line number	Diff line number	Diff line change
`@@ -122,6 +122,17 @@ protected void checkItem(OPFItem item, OPFHandler opfHandler)`
`122`	`122`	`{`
`123`	`123`	`report.message(MessageId.OPF_091, item.getLocation());`
`124`	`124`	`}`
	`125`	`+`
	`126`	`+ // Register media overlay usage`
	`127`	`+ if (context.referenceRegistry.isPresent() && !Strings.isNullOrEmpty(item.getMediaOverlay()))`
	`128`	`+ {`
	`129`	`+ Optional<OPFItem> overlay = opfHandler.getItemById(item.getMediaOverlay());`
	`130`	`+ if (overlay.isPresent())`
	`131`	`+ {`
	`132`	`+ context.referenceRegistry.get().registerReference(overlay.get().getURL(),`
	`133`	`+ Reference.Type.MEDIA_OVERLAY, item.getLocation());`
	`134`	`+ }`
	`135`	`+ }`
`125`	`136`	`}`
`126`	`137`
`127`	`138`	`@Override`
`@@ -156,6 +167,18 @@ else if (!context.referenceRegistry.get().hasReferencesTo(item.getURL()))`
`156`	`167`	`}`
`157`	`168`	`}`
`158`	`169`
	`170`	`+ // check that resources in the manifest are referenced (usage report)`
	`171`	`+ // - search the reference registry`
	`172`	`+ // - report if no reference (of a publication-resource type) is found`
	`173`	`+ if (!(item.isInSpine() \|\| item.isNav() \|\| item.isNcx())`
	`174`	`+ && context.referenceRegistry.isPresent()`
	`175`	`+ && context.referenceRegistry.get().asList().stream()`
	`176`	`+ .noneMatch(ref -> ref.targetResource.equals(item.getURL())`
	`177`	`+ && ref.type.isPublicationResourceReference()))`
	`178`	`+ {`
	`179`	`+ report.message(MessageId.OPF_097, item.getLocation(), item.getPath());`
	`180`	`+ }`
	`181`	`+`
`159`	`182`	`if (isBlessedItemType(mediatype, version))`
`160`	`183`	`{`
`161`	`184`	`// check whether media-overlay attribute needs to be specified`