Add INFO message to site modules showing the filename in case of issues (#961)

This PR uses the new 'reference' parameter in Doxia Parsers
to print the source filename when an issue is detected.
This is compatible and extends the features in 'logHandler'.

Fixes #323

Author: abelsromero

CHANGELOG.adoc

@@ -29,7 +29,7 @@ Improvements::
   * Sections are now wrapped in <div> in (asciidoctor-parser-doxia-module) (#944)
   * Add support for inline and Example blocks (asciidoctor-parser-doxia-module) (#938)
   * Add support for captioned titles in appendixes, tables, listing, figure, and examples (asciidoctor-parser-doxia-module) (#938)
-
+  * Add INFO message to site modules showing the filename in case of issues (#323)
 
 Build / Infrastructure::
 

asciidoctor-converter-doxia-module/src/main/java/org/asciidoctor/maven/site/AsciidoctorConverterDoxiaParser.java

@@ -17,6 +17,7 @@
 import org.asciidoctor.Options;
 import org.asciidoctor.OptionsBuilder;
 import org.asciidoctor.SafeMode;
+import org.asciidoctor.maven.commons.StringUtils;
 import org.asciidoctor.maven.log.LogHandler;
 import org.asciidoctor.maven.log.LogRecordFormatter;
 import org.asciidoctor.maven.log.LogRecordsProcessors;
@@ -82,15 +83,21 @@ public void parse(Reader reader, Sink sink, String reference) throws ParseExcept
         }
 
         final LogHandler logHandler = getLogHandlerConfig(siteConfig);
-        final MemoryLogHandler memoryLogHandler = asciidoctorLoggingSetup(asciidoctor, logHandler, siteDirectory);
+        final MemoryLogHandler memoryLogHandler = asciidoctorLoggingSetup(asciidoctor, siteDirectory);
 
         final SiteConverterDecorator siteConverter = new SiteConverterDecorator(asciidoctor);
         final Result headerMetadata = siteConverter.process(source, conversionConfig.getOptions());
 
         try {
             // process log messages according to mojo configuration
-            new LogRecordsProcessors(logHandler, siteDirectory, errorMessage -> logger.error(errorMessage))
-                .processLogRecords(memoryLogHandler);
+            if (!memoryLogHandler.isEmpty()) {
+                logger.info("Issues found in: {}", reference);
+                if (logHandler.getOutputToConsole() && StringUtils.isNotBlank(reference)) {
+                    memoryLogHandler.processAll();
+                }
+                new LogRecordsProcessors(logHandler, siteDirectory, errorMessage -> logger.error(errorMessage))
+                    .processLogRecords(memoryLogHandler);
+            }
         } catch (Exception exception) {
             throw new ParseException(exception.getMessage(), exception);
         }
@@ -101,10 +108,9 @@ public void parse(Reader reader, Sink sink, String reference) throws ParseExcept
         sink.rawText(headerMetadata.getHtml());
     }
 
+    private MemoryLogHandler asciidoctorLoggingSetup(Asciidoctor asciidoctor, File siteDirectory) {
 
-    private MemoryLogHandler asciidoctorLoggingSetup(Asciidoctor asciidoctor, LogHandler logHandler, File siteDirectory) {
-
-        final MemoryLogHandler memoryLogHandler = new MemoryLogHandler(logHandler.getOutputToConsole(),
+        final MemoryLogHandler memoryLogHandler = new MemoryLogHandler(false,
             logRecord -> logger.info(LogRecordFormatter.format(logRecord, siteDirectory)));
         asciidoctor.registerLogHandler(memoryLogHandler);
         // disable default console output of AsciidoctorJ

asciidoctor-maven-commons/src/main/java/org/asciidoctor/maven/log/MemoryLogHandler.java

@@ -14,10 +14,11 @@
  * AsciidoctorJ LogHandler that stores records in memory.
  *
  * @author abelsromero
+ * @since 1.5.7
  */
 public class MemoryLogHandler implements LogHandler {
 
-    final List<LogRecord> records = new ArrayList<>();
+    private final List<LogRecord> records = new ArrayList<>();
 
     private final Boolean outputToConsole;
     private final Consumer<LogRecord> recordConsumer;
@@ -46,8 +47,8 @@ public void clear() {
      */
     public List<LogRecord> filter(Severity severity) {
         return this.records.stream()
-                .filter(record -> severityIsHigher(record, severity))
-                .collect(Collectors.toList());
+            .filter(record -> severityIsHigher(record, severity))
+            .collect(Collectors.toList());
     }
 
     /**
@@ -58,8 +59,8 @@ public List<LogRecord> filter(Severity severity) {
      */
     public List<LogRecord> filter(String text) {
         return this.records.stream()
-                .filter(record -> messageContains(record, text))
-                .collect(Collectors.toList());
+            .filter(record -> messageContains(record, text))
+            .collect(Collectors.toList());
     }
 
     /**
@@ -71,8 +72,27 @@ public List<LogRecord> filter(String text) {
      */
     public List<LogRecord> filter(Severity severity, String text) {
         return this.records.stream()
-                .filter(record -> severityIsHigher(record, severity) && messageContains(record, text))
-                .collect(Collectors.toList());
+            .filter(record -> severityIsHigher(record, severity) && messageContains(record, text))
+            .collect(Collectors.toList());
+    }
+
+    /**
+     * Returns whether error messages have been captured or no.
+     *
+     * @return true if no error messages are present
+     * @since 3.1.0
+     */
+    public boolean isEmpty() {
+        return records.isEmpty();
+    }
+
+    /**
+     * Processes all stored log records.
+     *
+     * @since 3.1.0
+     */
+    public void processAll() {
+        records.forEach(recordConsumer::accept);
     }
 
     private static boolean severityIsHigher(LogRecord record, Severity severity) {
@@ -82,4 +102,5 @@ private static boolean severityIsHigher(LogRecord record, Severity severity) {
     private static boolean messageContains(LogRecord record, String text) {
         return record.getMessage().contains(text);
     }
+
 }

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/parser/AsciidoctorAstDoxiaParser.java

@@ -20,6 +20,7 @@
 import org.asciidoctor.OptionsBuilder;
 import org.asciidoctor.SafeMode;
 import org.asciidoctor.ast.Document;
+import org.asciidoctor.maven.commons.StringUtils;
 import org.asciidoctor.maven.log.LogHandler;
 import org.asciidoctor.maven.log.LogRecordFormatter;
 import org.asciidoctor.maven.log.LogRecordsProcessors;
@@ -90,7 +91,7 @@ public void parse(Reader reader, Sink sink, String reference) throws ParseExcept
         }
 
         final LogHandler logHandler = getLogHandlerConfig(siteConfig);
-        final MemoryLogHandler memoryLogHandler = asciidoctorLoggingSetup(asciidoctor, logHandler, siteDirectory);
+        final MemoryLogHandler memoryLogHandler = asciidoctorLoggingSetup(asciidoctor, siteDirectory);
 
         if (isNotBlank(reference))
             logger.debug("Document loaded: {}", reference);
@@ -99,14 +100,18 @@ public void parse(Reader reader, Sink sink, String reference) throws ParseExcept
 
         try {
             // process log messages according to mojo configuration
-            new LogRecordsProcessors(logHandler, siteDirectory, errorMessage -> logger.error(errorMessage))
-                .processLogRecords(memoryLogHandler);
-
+            if (!memoryLogHandler.isEmpty()) {
+                logger.info("Issues found in: {}", reference);
+                if (logHandler.getOutputToConsole() && StringUtils.isNotBlank(reference)) {
+                    memoryLogHandler.processAll();
+                }
+                new LogRecordsProcessors(logHandler, siteDirectory, errorMessage -> logger.error(errorMessage))
+                    .processLogRecords(memoryLogHandler);
+            }
         } catch (Exception exception) {
             throw new ParseException(exception.getMessage(), exception);
         }
 
-
         HeaderMetadata headerMetadata = HeaderMetadata.from(document);
 
         new HeadParser(sink)
@@ -116,9 +121,9 @@ public void parse(Reader reader, Sink sink, String reference) throws ParseExcept
             .sink(document);
     }
 
-    private MemoryLogHandler asciidoctorLoggingSetup(Asciidoctor asciidoctor, LogHandler logHandler, File siteDirectory) {
+    private MemoryLogHandler asciidoctorLoggingSetup(Asciidoctor asciidoctor, File siteDirectory) {
 
-        final MemoryLogHandler memoryLogHandler = new MemoryLogHandler(logHandler.getOutputToConsole(),
+        final MemoryLogHandler memoryLogHandler = new MemoryLogHandler(false,
             logRecord -> logger.info(LogRecordFormatter.format(logRecord, siteDirectory)));
         asciidoctor.registerLogHandler(memoryLogHandler);
         // disable default console output of AsciidoctorJ

docs/modules/site-integration/pages/converter-module-setup-and-configuration.adoc

@@ -157,5 +157,4 @@ Enables processing of Asciidoctor messages.
 For example to hide them, enable finer detail or fail the build on certain scenarios (e.g. missing included files).
 To see all options refer to the main plugin xref:plugin:goals/http.adoc#configuration-logHandler[logHandler configuration].
 +
-IMPORTANT: Due to limitations in how Maven site integration works, it is not possible to provide the filename in the error message.
-We are aware this is not ideal and are tracking any development on the Maven side towards this goal (https://issues.apache.org/jira/browse/DOXIA-555[DOXIA-555]).
+NOTE: Since v3.1.0+ the source filename will be displayed alongside issues found during conversion.

docs/modules/site-integration/pages/parser-module-setup-and-configuration.adoc

@@ -159,8 +159,7 @@ Enables processing of Asciidoctor messages.
 For example to hide them, enable finer detail or fail the build on certain scenarios (e.g. missing included files).
 To see all options refer to the main plugin xref:plugin:goals/http.adoc#configuration-logHandler[logHandler configuration].
 +
-IMPORTANT: Due to limitations in how Maven site integration works, it is not possible to provide the filename in the error message.
-We are aware this is not ideal and are tracking any development on the Maven side towards this goal (https://issues.apache.org/jira/browse/DOXIA-555[DOXIA-555]).
+NOTE: Since v3.1.0+ the source filename will be displayed alongside issues found during conversion.
 
 [#supported-asciidoc-elements]
 == Supported AsciiDoc elements