From 430d977b68629121ca4d8b47c5ff79d31d73957c Mon Sep 17 00:00:00 2001 From: Slawomir Jaranowski Date: Sat, 29 Jun 2024 18:05:54 +0200 Subject: [PATCH] Allow to skip generating empty report --- .../codehaus/mojo/taglist/FileAnalyser.java | 23 +--- .../mojo/taglist/ReportGenerator.java | 6 +- .../codehaus/mojo/taglist/TagListReport.java | 115 +++++++++++------- .../taglist/TaglistMojoBasicConfigTest.java | 8 +- .../mojo/taglist/TaglistMojoSkipTest.java | 20 +++ .../mojo/taglist/TaglistMojoTagsTest.java | 16 +-- .../taglist/stubs/NoSourcesProjectStub.java | 44 +++++++ .../empty-comments-disabled-pom.xml | 3 +- .../unit/no-sources-test/default-pom.xml | 42 +++++++ .../unit/tag-test/not-start-line-tags-pom.xml | 3 +- .../source-code-variable-tags-pom.xml | 3 +- 11 files changed, 202 insertions(+), 81 deletions(-) create mode 100644 src/test/java/org/codehaus/mojo/taglist/TaglistMojoSkipTest.java create mode 100644 src/test/java/org/codehaus/mojo/taglist/stubs/NoSourcesProjectStub.java create mode 100644 src/test/resources/unit/no-sources-test/default-pom.xml diff --git a/src/main/java/org/codehaus/mojo/taglist/FileAnalyser.java b/src/main/java/org/codehaus/mojo/taglist/FileAnalyser.java index f74ca2a..e5f3672 100644 --- a/src/main/java/org/codehaus/mojo/taglist/FileAnalyser.java +++ b/src/main/java/org/codehaus/mojo/taglist/FileAnalyser.java @@ -25,6 +25,7 @@ import java.io.InputStreamReader; import java.io.LineNumberReader; import java.io.Reader; +import java.io.UncheckedIOException; import java.nio.file.Files; import java.util.ArrayList; import java.util.Collection; @@ -33,7 +34,6 @@ import org.apache.commons.lang.StringUtils; import org.apache.maven.plugin.logging.Log; -import org.apache.maven.reporting.MavenReportException; import org.codehaus.mojo.taglist.beans.FileReport; import org.codehaus.mojo.taglist.beans.TagReport; import org.codehaus.mojo.taglist.tags.TagClass; @@ -105,11 +105,6 @@ public class FileAnalyser { */ private final boolean emptyCommentsOn; - /** - * String used to indicate that there is no comment after the tag. - */ - private final String noCommentString; - /** * ArrayList of tag classes. */ @@ -128,7 +123,6 @@ public FileAnalyser(TagListReport report, List tagClasses) { sourceDirs = report.getSourceDirs(); encoding = report.getInputEncoding(); locale = report.getLocale(); - noCommentString = report.getBundle().getString("report.taglist.nocomment"); this.tagClasses = tagClasses; this.includes = report.getIncludesCommaSeparated(); this.excludes = report.getExcludesCommaSeparated(); @@ -138,9 +132,8 @@ public FileAnalyser(TagListReport report, List tagClasses) { * Execute the analysis for the configuration given by the TagListReport. * * @return a collection of TagReport objects. - * @throws MavenReportException the Maven report exception. */ - public Collection execute() throws MavenReportException { + public Collection execute() { List fileList = findFilesToScan(); for (File file : fileList) { @@ -162,16 +155,16 @@ public Collection execute() throws MavenReportException { * Gives the list of files to scan. * * @return a List of File objects. - * @throws MavenReportException the Maven report exception. */ - private List findFilesToScan() throws MavenReportException { + private List findFilesToScan() { List filesList = new ArrayList<>(); try { for (String sourceDir : sourceDirs) { filesList.addAll(FileUtils.getFiles(new File(sourceDir), includes, excludes)); } } catch (IOException e) { - throw new MavenReportException("Error while trying to find the files to scan.", e); + // TODO - fix with Doxia 2.x - canGenerateReport will have a checked exception + throw new UncheckedIOException("Error while trying to find the files to scan.", e); } return filesList; } @@ -219,11 +212,7 @@ public void scanFile(File file) { firstLine = StringUtils.removeEnd(firstLine, "*/"); // MTAGLIST-35 if (firstLine.isEmpty() || ":".equals(firstLine)) { // this is not a valid comment tag: nothing is written there - if (emptyCommentsOn) { - comment.append("--"); - comment.append(noCommentString); - comment.append("--"); - } else { + if (!emptyCommentsOn) { continue; } } else { diff --git a/src/main/java/org/codehaus/mojo/taglist/ReportGenerator.java b/src/main/java/org/codehaus/mojo/taglist/ReportGenerator.java index 4fb6660..7a65703 100644 --- a/src/main/java/org/codehaus/mojo/taglist/ReportGenerator.java +++ b/src/main/java/org/codehaus/mojo/taglist/ReportGenerator.java @@ -253,9 +253,13 @@ private void doFileDetailedPart(FileReport fileReport) { private void doCommentLine(FileReport fileReport, Integer lineNumber) { boolean linked = false; + String comment = fileReport.getComment(lineNumber); + if (comment == null || comment.isEmpty()) { + comment = "--" + bundle.getString("report.taglist.nocomment") + "--"; + } sink.tableRow(); sink.tableCell(); - sink.text(fileReport.getComment(lineNumber)); + sink.text(comment); sink.tableCell_(); sink.tableCell(); if (xrefLocation != null) { diff --git a/src/main/java/org/codehaus/mojo/taglist/TagListReport.java b/src/main/java/org/codehaus/mojo/taglist/TagListReport.java index b188efe..a38b4d3 100644 --- a/src/main/java/org/codehaus/mojo/taglist/TagListReport.java +++ b/src/main/java/org/codehaus/mojo/taglist/TagListReport.java @@ -31,7 +31,6 @@ import java.util.ResourceBundle; import java.util.concurrent.atomic.AtomicReference; -import org.apache.maven.doxia.siterenderer.Renderer; import org.apache.maven.model.ReportPlugin; import org.apache.maven.plugins.annotations.Mojo; import org.apache.maven.plugins.annotations.Parameter; @@ -70,7 +69,10 @@ public class TagListReport extends AbstractMavenReport { @Parameter(property = "sourceFileLocale", defaultValue = "en") private String sourceFileLocale; - /** Default locale used if the source file locale is null. */ + /** + * Default locale used if the source file locale is null. + */ + // TODO - please review default locale with Doxia 2.x private static final String DEFAULT_LOCALE = "en"; /** @@ -100,7 +102,6 @@ public class TagListReport extends AbstractMavenReport { /** * This parameter indicates whether for simple tags (like "TODO"), the analyzer should look for multiple line * comments. - * */ @Parameter(defaultValue = "true") private boolean multipleLineComments; @@ -191,13 +192,24 @@ public class TagListReport extends AbstractMavenReport { private String[] tags; + /** + * Skip generating report if no tags found in sources. + * + * @since 3.1.0 + */ + @Parameter(property = "taglist.skipEmptyReport", defaultValue = "false") + private boolean skipEmptyReport; + private final AtomicReference> sourceDirs = new AtomicReference<>(); + private Collection tagReportsResult; + /** * {@inheritDoc} * * @see org.apache.maven.reporting.AbstractMavenReport#executeReport(java.util.Locale) */ + @Override protected void executeReport(Locale locale) throws MavenReportException { this.currentLocale = locale; @@ -206,6 +218,47 @@ protected void executeReport(Locale locale) throws MavenReportException { + Charset.defaultCharset().displayName() + ", i.e. build is platform dependent!"); } + executeAnalysis(); + + // Renders the report + ReportGenerator generator = new ReportGenerator(this, tagReportsResult); + if (linkXRef) { + String relativePath = getRelativePath(xrefLocation); + if (xrefLocation.exists()) { + // XRef was already generated by manual execution of a lifecycle binding + generator.setXrefLocation(relativePath); + generator.setTestXrefLocation(getRelativePath(testXrefLocation)); + } else { + // Not yet generated - check if the report is on its way + + for (ReportPlugin report : + getProject().getModel().getReporting().getPlugins()) { + String artifactId = report.getArtifactId(); + if ("maven-jxr-plugin".equals(artifactId) || "jxr-maven-plugin".equals(artifactId)) { + getLog().error("Taglist plugin MUST be executed after the JXR plugin." + + " No links to xref were generated."); + } + } + } + + // TODO we have similar code in many plugins to generate xref links + // we can externalize it to one place + if (generator.getXrefLocation() == null) { + getLog().warn("Unable to locate Source XRef to link to - DISABLED"); + } + } + generator.generateReport(); + + // Generate the XML report + generateXmlReport(tagReportsResult); + } + + private void executeAnalysis() { + if (tagReportsResult != null) { + // already analyzed + return; + } + // Create the tag classes List tagClasses = new ArrayList<>(); @@ -256,37 +309,7 @@ protected void executeReport(Locale locale) throws MavenReportException { // let's proceed to the analysis FileAnalyser fileAnalyser = new FileAnalyser(this, tagClasses); - Collection tagReports = fileAnalyser.execute(); - - // Renders the report - ReportGenerator generator = new ReportGenerator(this, tagReports); - if (linkXRef) { - String relativePath = getRelativePath(xrefLocation); - if (xrefLocation.exists()) { - // XRef was already generated by manual execution of a lifecycle binding - generator.setXrefLocation(relativePath); - generator.setTestXrefLocation(getRelativePath(testXrefLocation)); - } else { - // Not yet generated - check if the report is on its way - - for (ReportPlugin report : - getProject().getModel().getReporting().getPlugins()) { - String artifactId = report.getArtifactId(); - if ("maven-jxr-plugin".equals(artifactId) || "jxr-maven-plugin".equals(artifactId)) { - getLog().error("Taglist plugin MUST be executed after the JXR plugin." - + " No links to xref were generated."); - } - } - } - - if (generator.getXrefLocation() == null) { - getLog().warn("Unable to locate Source XRef to link to - DISABLED"); - } - } - generator.generateReport(); - - // Generate the XML report - generateXmlReport(tagReports); + tagReportsResult = fileAnalyser.execute(); } private TagClass createTagClass(String tag) { @@ -372,12 +395,19 @@ private String getRelativePath(File location) { * * @see org.apache.maven.reporting.MavenReport#canGenerateReport() */ + @Override public boolean canGenerateReport() { boolean canGenerate = !getSourceDirs().isEmpty(); if (aggregate && !getProject().isExecutionRoot()) { canGenerate = false; } - return canGenerate; + + if (canGenerate) { + executeAnalysis(); + return !skipEmptyReport || tagReportsResult.stream().anyMatch(tagReport -> tagReport.getTagCount() > 0); + } + + return false; } /** @@ -401,7 +431,7 @@ private List pruneSourceDirs(List sourceDirectories) throws IOEx * * @param dir the source directory. * @return true if the folder or one of its subfolders contains at least 1 source file that matches - * includes/excludes. + * includes/excludes. */ private boolean hasSources(File dir) throws IOException { if (dir.exists() && dir.isDirectory()) { @@ -537,20 +567,12 @@ public boolean isShowEmptyDetails() { return showEmptyDetails; } - /** - * {@inheritDoc} - * - * @see org.apache.maven.reporting.AbstractMavenReport#getSiteRenderer() - */ - protected Renderer getSiteRenderer() { - return siteRenderer; - } - /** * {@inheritDoc} * * @see org.apache.maven.reporting.AbstractMavenReport#getOutputDirectory() */ + @Override protected String getOutputDirectory() { return outputDirectory.getAbsolutePath(); } @@ -569,6 +591,7 @@ protected String getXMLOutputDirectory() { * * @see org.apache.maven.reporting.MavenReport#getDescription(java.util.Locale) */ + @Override public String getDescription(Locale locale) { return getBundle(locale).getString("report.taglist.description"); } @@ -578,6 +601,7 @@ public String getDescription(Locale locale) { * * @see org.apache.maven.reporting.MavenReport#getName(java.util.Locale) */ + @Override public String getName(Locale locale) { return getBundle(locale).getString("report.taglist.name"); } @@ -587,6 +611,7 @@ public String getName(Locale locale) { * * @see org.apache.maven.reporting.MavenReport#getOutputName() */ + @Override public String getOutputName() { return "taglist"; } diff --git a/src/test/java/org/codehaus/mojo/taglist/TaglistMojoBasicConfigTest.java b/src/test/java/org/codehaus/mojo/taglist/TaglistMojoBasicConfigTest.java index fd0ea8c..0b2616b 100644 --- a/src/test/java/org/codehaus/mojo/taglist/TaglistMojoBasicConfigTest.java +++ b/src/test/java/org/codehaus/mojo/taglist/TaglistMojoBasicConfigTest.java @@ -127,11 +127,9 @@ public void testEmptyCommentsDisabled() throws Exception { mojo.execute(); - String htmlString = super.getGeneratedOutput(mojo); - - // Check to see that there was zero tags found - String expected = "@empty_comment0"; - assertTrue("Missing tag result.", htmlString.contains(expected)); + File outputDirectory = mojo.getReportOutputDirectory(); + assertNotNull(outputDirectory); + assertFalse(outputDirectory.exists()); } /** diff --git a/src/test/java/org/codehaus/mojo/taglist/TaglistMojoSkipTest.java b/src/test/java/org/codehaus/mojo/taglist/TaglistMojoSkipTest.java new file mode 100644 index 0000000..04dddba --- /dev/null +++ b/src/test/java/org/codehaus/mojo/taglist/TaglistMojoSkipTest.java @@ -0,0 +1,20 @@ +package org.codehaus.mojo.taglist; + +import java.io.File; + +public class TaglistMojoSkipTest extends AbstractTaglistMojoTestCase { + + public void testNoSourcesDirectory() throws Exception { + File pluginXmlFile = new File(getBasedir(), "src/test/resources/unit/no-sources-test/default-pom.xml"); + + TagListReport mojo = super.getTagListReport(pluginXmlFile); + + // Run the TagList mojo + mojo.execute(); + + // output should not be generated + File outputDirectory = mojo.getReportOutputDirectory(); + assertNotNull(outputDirectory); + assertFalse(outputDirectory.exists()); + } +} diff --git a/src/test/java/org/codehaus/mojo/taglist/TaglistMojoTagsTest.java b/src/test/java/org/codehaus/mojo/taglist/TaglistMojoTagsTest.java index aa04419..d971cc6 100644 --- a/src/test/java/org/codehaus/mojo/taglist/TaglistMojoTagsTest.java +++ b/src/test/java/org/codehaus/mojo/taglist/TaglistMojoTagsTest.java @@ -170,11 +170,9 @@ public void testNotAtStartOfLineTags() throws Exception { // Run the TagList mojo mojo.execute(); - String htmlString = super.getGeneratedOutput(mojo); - - // Check to see a tag not at the start of a line does not show up. - String expected = "not_start_of_line_tag0"; - assertTrue("Incorrect tag not at start of line tag result.", htmlString.contains(expected)); + File outputDirectory = mojo.getReportOutputDirectory(); + assertNotNull(outputDirectory); + assertFalse(outputDirectory.exists()); } /** @@ -193,10 +191,8 @@ public void testSourceCodeVariablesTags() throws Exception { // Run the TagList mojo mojo.execute(); - String htmlString = super.getGeneratedOutput(mojo); - - // Check to see a source code variable does not show up. - String expected = "source_code_variable_tag0"; - assertTrue("Incorrect source code variable tag result.", htmlString.contains(expected)); + File outputDirectory = mojo.getReportOutputDirectory(); + assertNotNull(outputDirectory); + assertFalse(outputDirectory.exists()); } } diff --git a/src/test/java/org/codehaus/mojo/taglist/stubs/NoSourcesProjectStub.java b/src/test/java/org/codehaus/mojo/taglist/stubs/NoSourcesProjectStub.java new file mode 100644 index 0000000..3ab4709 --- /dev/null +++ b/src/test/java/org/codehaus/mojo/taglist/stubs/NoSourcesProjectStub.java @@ -0,0 +1,44 @@ +package org.codehaus.mojo.taglist.stubs; + +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import java.util.Collections; +import java.util.List; + +import org.codehaus.plexus.PlexusTestCase; + +/** + * The Maven Project stub file for testing the different types of tags. + *

+ * This stub is used to get the test and source file directories. This + * allows the TagList plugin unit tests run against the unit test directories + * instead of using the default project directories. + */ +public class NoSourcesProjectStub extends org.apache.maven.plugin.testing.stubs.MavenProjectStub { + public List getCompileSourceRoots() { + return Collections.singletonList( + PlexusTestCase.getBasedir() + "/target/test-classes/unit/no-sources-test/java-sources"); + } + + public List getTestCompileSourceRoots() { + return Collections.singletonList( + PlexusTestCase.getBasedir() + "/target/test-classes/unit/no-sources-test/test-sources"); + } +} diff --git a/src/test/resources/unit/basic-config-test/empty-comments-disabled-pom.xml b/src/test/resources/unit/basic-config-test/empty-comments-disabled-pom.xml index d39c35f..493c240 100644 --- a/src/test/resources/unit/basic-config-test/empty-comments-disabled-pom.xml +++ b/src/test/resources/unit/basic-config-test/empty-comments-disabled-pom.xml @@ -34,7 +34,8 @@ taglist-maven-plugin - ${basedir}/target/test-classes/unit/basic-config-test/outputDirectory + ${basedir}/target/test-classes/unit/basic-config-test/outputDirectory-empty-comments-disabled + true false @empty_comment diff --git a/src/test/resources/unit/no-sources-test/default-pom.xml b/src/test/resources/unit/no-sources-test/default-pom.xml new file mode 100644 index 0000000..6dd944b --- /dev/null +++ b/src/test/resources/unit/no-sources-test/default-pom.xml @@ -0,0 +1,42 @@ + + + + + org.codehaus.mojo + test-taglist-mojo + 1.0-SNAPSHOT + jar + Test TagList Mojo + 4.0.0 + + UTF-8 + + + + + taglist-maven-plugin + + + ${basedir}/target/test-classes/unit/no-sources-test/outputDirectory + + + + + diff --git a/src/test/resources/unit/tag-test/not-start-line-tags-pom.xml b/src/test/resources/unit/tag-test/not-start-line-tags-pom.xml index 15289b5..0d27563 100644 --- a/src/test/resources/unit/tag-test/not-start-line-tags-pom.xml +++ b/src/test/resources/unit/tag-test/not-start-line-tags-pom.xml @@ -34,7 +34,8 @@ taglist-maven-plugin - ${basedir}/target/test-classes/unit/tag-test/outputDirectory + ${basedir}/target/test-classes/unit/tag-test/outputDirectory-not-start-line-tags + true not_start_of_line_tag diff --git a/src/test/resources/unit/tag-test/source-code-variable-tags-pom.xml b/src/test/resources/unit/tag-test/source-code-variable-tags-pom.xml index 494d722..f72f390 100644 --- a/src/test/resources/unit/tag-test/source-code-variable-tags-pom.xml +++ b/src/test/resources/unit/tag-test/source-code-variable-tags-pom.xml @@ -34,7 +34,8 @@ taglist-maven-plugin - ${basedir}/target/test-classes/unit/tag-test/outputDirectory + ${basedir}/target/test-classes/unit/tag-test/outputDirectory-source-code-variable-tags + true source_code_variable_tag