diff --git a/README.adoc b/README.adoc index d6bbe9d8..608f4753 100644 --- a/README.adoc +++ b/README.adoc @@ -28,15 +28,14 @@ image:https://img.shields.io/github/issues/aim42/htmlSanityCheck.svg[link="https HSC can be currently used * As a xref:{xrefToGradlePlugin}#sec:usage[Gradle plugin], or +* An https://maven.apache.org[Apache Maven] Plugin or * Programmatically from Java or other JVM languages (TBD). [NOTE] .Future releases ==== In the future, we plan to provide - -* A standalone Java (CLI) executable, and -* An https://maven.apache.org[Apache Maven] Plugin. +* A standalone Java (CLI) executable. ==== [[sec:installation]] diff --git a/generate-pages b/generate-pages index 8a8fd081..fd2928a0 100755 --- a/generate-pages +++ b/generate-pages @@ -1,3 +1,5 @@ + + #!/usr/bin/env bash : "${DTC_VERSION:=latest}" diff --git a/htmlSanityCheck-maven-plugin/README.adoc b/htmlSanityCheck-maven-plugin/README.adoc index 43f49edc..29e58409 100644 --- a/htmlSanityCheck-maven-plugin/README.adoc +++ b/htmlSanityCheck-maven-plugin/README.adoc @@ -27,7 +27,7 @@ Use the following snippet inside a Maven build file: org.aim42.htmlSanityCheck htmlSanityCheck-maven-plugin - 2.0.0-rc1 // <1> + {hsc-version} // <1> compile @@ -48,6 +48,19 @@ Use the following snippet inside a Maven build file: <2> List the files you want tio check here. <3> Directory where the HTML files are located. +[[box:current-version]] +[IMPORTANT] +.Latest (development) versions +==== +* The latest https://github.com/aim42/htmlSanityCheck/releases[release version] is defined in https://github.com/aim42/htmlSanityCheck/blob/main/gradle.properties[`gradle.properties` on `main` branch]. +* The current (development) version is defined in {gradleProperties} ++ +[source] +.Development version +---- +include::../gradle.properties[tag=version] +---- +==== [[sec:usage]] == Usage @@ -120,7 +133,7 @@ Type: List. + Default: + -[source,groovy] +[source,java] ---- include::../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[tag=HTTP_WARNING_CODES,indent=0] // Redirects included @@ -154,7 +167,7 @@ Type: List. + Default: + -[source,groovy] +[source,java] ---- include::../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[tag=HTTP_SUCCESS_CODES,indent=0] ---- @@ -172,7 +185,7 @@ The mentioned configurations effectively move the configured codes around, i.e., === Small Example `build.maven` -[source,groovy] +[source,xml] ---- tbd ---- @@ -180,7 +193,7 @@ tbd === Extended example .`build.maven` -[source,groovy,subs='attributes'] +[source,xml,subs='attributes'] ---- tbd diff --git a/htmlSanityCheck-maven-plugin/src/main/java/org/aim42/htmlSanityCheck/htmlsanitycheckmavenplugin/HtmlSanityCheckMojo.java b/htmlSanityCheck-maven-plugin/src/main/java/org/aim42/htmlSanityCheck/htmlsanitycheckmavenplugin/HtmlSanityCheckMojo.java index 59e72e93..36a49573 100644 --- a/htmlSanityCheck-maven-plugin/src/main/java/org/aim42/htmlSanityCheck/htmlsanitycheckmavenplugin/HtmlSanityCheckMojo.java +++ b/htmlSanityCheck-maven-plugin/src/main/java/org/aim42/htmlSanityCheck/htmlsanitycheckmavenplugin/HtmlSanityCheckMojo.java @@ -21,49 +21,169 @@ /* No Javadoc for class due to https://stackoverflow.com/questions/28428833/maven-error-when-doing-packaging + + This Mojo-Class is the core of the maven plugin. + It uses the maven capabilities to take the configuration parameters from the mavens pom.xml and calls the hsc core + with the parameters. + + It does not include any checking functionality itself. */ @Mojo(name = "sanity-check", defaultPhase = LifecyclePhase.VERIFY, requiresDependencyResolution = ResolutionScope.RUNTIME) public class HtmlSanityCheckMojo extends AbstractMojo { - + /** + * (optional) Directory where the checking results written to. + *

+ * Type: Directory. + *

+ * Default: {buildDir}/reports/htmlSanityCheck/ + */ @Parameter(defaultValue = "${project.build.directory}/reports/htmlSanityCheck/", required = true) private File checkingResultsDir; + + /** + * (optional) Directory where the results are written to in JUnit XML format. JUnit XML can be read by many tools, including CI environments. + *

+ * Type: Directory. + *

+ * Default: {buildDir}/test-results/htmlchecks/ + */ @Parameter(defaultValue = "${project.build.directory}/test-results/htmlSanityCheck/", required = true) private File junitResultsDir; + /** + * (mandatory) + * Directory where the HTML files are located. + */ @Parameter private File sourceDir; + /** + * (optional) An override to process several source files, which may be a subset of all files available in {sourceDir}. + *

+ * Type: org.maven.api.file.FileCollection. + *

+ * Default: All files in {sourceDir} whose names end with .html. + */ @Parameter private Set sourceDocuments; + /** + * (optional) + * Fail the build if any error was found in the checked pages. + *

+ * Type: Boolean. + *

+ * Default: false. + */ @Parameter(defaultValue = "false") private boolean failOnErrors; + /** + * (optional) Timeout for http requests in ms. + *

+ * Type: Integer. + *

+ * Default: 5000. + */ @Parameter(defaultValue = "5000") private int httpConnectionTimeout; + /** + * (optional) Ignore localhost as hostname. + *

+ * Type: Boolean. + *

+ * Default: false. + */ @Parameter(defaultValue = "false") private boolean ignoreLocalHost; + /** + * (optional) Ignore IP addresses as hostname. + *

+ * Type: Boolean. + *

+ * Default: false. + */ @Parameter(defaultValue = "false") private boolean ignoreIPAddresses; + /** + * (optional) Additional HTTP response codes treated as warning. + *

+ * Type: List. + *

+ * Default: + *

+ * 100, 101, 102 + * // Redirects included + * 301, 302, 303, 307, 308 + * HTTP Redirects + * Note that HTTP redirects are treated as a warning to make the user aware of the correct or new location (cf. Issue 244). Some HSC reports often contain the respective location. + */ @Parameter private Set httpWarningCodes; + /** + * (optional) Additional HTTP response codes treated as error. + *

+ * Type: List. + *

+ * Default: + *

+ * 400, 401, 402, 403, 404, + * 405, 406, 407, 408, 409, + * 410, 411, 412, 413, 414, + * 415, 416, 417, 418, 421, + * 422, 423, 424, 425, 426, + * 428, 429, 431, 451, + * 500, 501, 502, 503, 504, + * 505, 506, 507, 508, 510, + * 511 + */ @Parameter private Set httpErrorCodes; + /** + * (optional) Additional HTTP response codes treated as success. + *

+ * Type: List. + *

+ * Default: + *

+ * 200, 201, 202, 203, 204, + * 205, 206, 207, 208, 226 + */ @Parameter private Set httpSuccessCodes; + /** + * (optional) The set of checker classes to be executed. + *

+ * Type: List. + *

+ * Default: All available checker classes. + *

+ * Checker Classes + * // Keep the list ordering to ensure + * // report ordering comparability + * // with HSC 1.x versions + * MissingAltInImageTagsChecker.class, + * MissingImageFilesChecker.class, + * DuplicateIdChecker.class, + * BrokenHttpLinksChecker.class, + * ImageMapChecker.class, + * BrokenCrossReferencesChecker.class, + * MissingLocalResourcesChecker.class + */ @Parameter private List> checkerClasses = AllCheckers.CHECKER_CLASSES; + // tag::maven-plugin-implementation[] public void execute() throws MojoExecutionException { logBuildParameter(); @@ -108,6 +228,7 @@ public void execute() throws MojoExecutionException { throw new MojoExecutionException(e); } } + // end::maven-plugin-implementation[] private void logBuildParameter() { // Log build parameters @@ -142,7 +263,7 @@ protected Configuration setupConfiguration() { if (httpSuccessCodes != null && !httpSuccessCodes.isEmpty()) { result.overrideHttpSuccessCodes(httpSuccessCodes); } - if (httpErrorCodes != null && !httpErrorCodes.isEmpty()) { + if (httpErrorCodes != null && !httpErrorCodes.isEmpty()) { result.overrideHttpErrorCodes(httpErrorCodes); } if (httpErrorCodes != null && !httpWarningCodes.isEmpty()) { @@ -154,3 +275,20 @@ protected Configuration setupConfiguration() { } + +/*======================================================================== + Copyright Gernot Starke and aim42 contributors + + Licensed 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. + ========================================================================*/ diff --git a/src/docs/arc42/chapters/_config.adoc b/src/docs/arc42/chapters/_config.adoc index b3bf41e6..e388a92c 100644 --- a/src/docs/arc42/chapters/_config.adoc +++ b/src/docs/arc42/chapters/_config.adoc @@ -33,14 +33,18 @@ ifndef::projectRootDir[:projectRootDir: ../../../..] :core-test-path: {projectRootDir}/htmlSanityCheck-core/src/test/groovy/org/aim42 :gradle-plugin-source-path: {projectRootDir}/htmlSanityCheck-gradle-plugin/src/main/groovy/org/aim42 :gradle-plugin-test-path: {projectRootDir}/htmlSanityCheck-gradle-plugin/src/test/groovy/org/aim42 +:maven-plugin-source-path: {projectRootDir}/htmlSanityCheck-maven-plugin/src/main/java/org/aim42 +:maven-plugin-test-path: {projectRootDir}/htmlSanityCheck-maven-plugin/src/test/java/org/aim42 :asciidoctor-gradle-plugin-url: https://github.com/asciidoctor/asciidoctor-gradle-plugin +:asciidoctor-maven-plugin-url: https://github.com/asciidoctor/asciidoctor-maven-plugin :arc42-url: https://github.com/arc42 :aim42-url: https://github.com/aim42 :asciidoc-url: https://asciidoctor.org :gradle-url: https://gradle.org/ +:maven-url: https://maven.apache.org :groovy-url: https://www.groovy-lang.org/ :template-method-pattern-url: https://sourcemaking.com/design_patterns/template_method @@ -60,6 +64,7 @@ ifndef::projectRootDir[:projectRootDir: ../../../..] :xrefConceptHtmlEncapsulation: <> :xrefConceptReporting: <> :xrefConceptGradlePlugin: <> +:xrefConceptMavenPlugin: <> :xrefDeplomentView: <> :xrefRequirementsGradleIntegration: <> :xrefRequirementsRequiredChecks: <> @@ -79,6 +84,7 @@ ifdef::jbake-type[] :xrefConceptHtmlEncapsulation: xref:chap-08-Concepts.adoc#sec:html-encapsulation[HTML encapsulation concept] :xrefConceptReporting: xref:chap-08-Concepts.adoc#sec:reporting-concept[reporting concept] :xrefConceptGradlePlugin: xref:chap-08-Concepts.adoc#sec:gradle-plugin-concept[Gradle plugin concept] +:xrefConceptMavenPlugin: xref:chap-08-Concepts.adoc#sec:maven-plugin-concept[Maven plugin concept] :xrefDeplomentView: xref:chap-07-Deployment.adoc#sec:deployment-view[deployment view] :xrefRequirementsGradleIntegration: xref:chap-01-Requirements.adoc#sec:requirements[required Gradle integration] :xrefRequirementsRequiredChecks: xref:chap-01-Requirements.adoc#sec:requiredChecks[Required Checks] diff --git a/src/docs/arc42/chapters/chap-01-Requirements.adoc b/src/docs/arc42/chapters/chap-01-Requirements.adoc index 7ca01abe..ccb851bd 100644 --- a/src/docs/arc42/chapters/chap-01-Requirements.adoc +++ b/src/docs/arc42/chapters/chap-01-Requirements.adoc @@ -33,7 +33,9 @@ Reports its results either on the console or as HTML report. HSC can run * From the command line (CLI), or -* As {gradle-url}[Gradle]-plugin. +* As {gradle-url}[Gradle]-plugin or +* As {maven-url}[Maven]-plugin. + .Terminology: What Can Go Wrong in HTML Files? diff --git a/src/docs/arc42/chapters/chap-04-SolutionStrategy.adoc b/src/docs/arc42/chapters/chap-04-SolutionStrategy.adoc index 3fbc4862..f3579759 100644 --- a/src/docs/arc42/chapters/chap-04-SolutionStrategy.adoc +++ b/src/docs/arc42/chapters/chap-04-SolutionStrategy.adoc @@ -7,10 +7,11 @@ include::_config.adoc[] :filename: arc42/chapters/chap-04-SolutionStrategy.adoc -* Implement HSC in Java with minimal -external dependencies. Wrap this implementation into a {gradle-url}[Gradle] -plugin, so it can be used within automated builds. Details are given -in the {xrefConceptGradlePlugin}. +* Implement HSC in Java with minimal external dependencies. +** Implement a core libary for the functionality with minimal external dependencies and tool independent. +** Wrap this implementation into a {gradle-url}[Gradle] and a {maven-url}[Maven] plugin, so it can be used within automated builds. +Details are given in the {xrefConceptGradlePlugin} and {xrefConceptMavenPlugin}. +** Create a command line interface. * Apply the _template-method-pattern_ (see e.g. {template-method-pattern-url}) to enable: ** multiple checking algorithms. See the {xrefConceptCheckingAlgorithms}, diff --git a/src/docs/arc42/chapters/chap-05-BuildingBlocks.adoc b/src/docs/arc42/chapters/chap-05-BuildingBlocks.adoc index 82f3bcd5..8c068797 100644 --- a/src/docs/arc42/chapters/chap-05-BuildingBlocks.adoc +++ b/src/docs/arc42/chapters/chap-05-BuildingBlocks.adoc @@ -33,7 +33,8 @@ Contained Blackboxes:: | <> | hsc core: html parsing and sanity checking, configuration, reporting. | HSC Gradle Plugin | integrates the Gradle build tool with HSC, enabling arbitrary gradle builds to use HSC functionality. -| HSC Maven Plugin | (planned, not yet implemented) +| HSC Maven Plugin | integrates the Maven build tool with HSC, +enabling arbitrary maven builds to use HSC functionality. | HSC Graphical Interface | (planned, not implemented) |=== diff --git a/src/docs/arc42/chapters/chap-08-Concepts.adoc b/src/docs/arc42/chapters/chap-08-Concepts.adoc index b48d1e12..16dc4569 100644 --- a/src/docs/arc42/chapters/chap-08-Concepts.adoc +++ b/src/docs/arc42/chapters/chap-08-Concepts.adoc @@ -9,6 +9,7 @@ include::_config.adoc[] include::chap-08-checking-domain.adoc[] include::chap-08-gradle-plugin.adoc[] +include::chap-08-maven-plugin.adoc[] include::chap-08-checking-algorithms.adoc[] include::chap-08-html-encapsulation.adoc[] diff --git a/src/docs/arc42/chapters/chap-08-maven-plugin.adoc b/src/docs/arc42/chapters/chap-08-maven-plugin.adoc new file mode 100644 index 00000000..3915b1ff --- /dev/null +++ b/src/docs/arc42/chapters/chap-08-maven-plugin.adoc @@ -0,0 +1,34 @@ +:jbake-menu: - +include::_config.adoc[] +[[sec:maven-plugin-concept]] +=== Maven Plugin Concept and Development + +:filename: arc42/chapters/chap-08-maven-plugin.adoc +include::../_feedback.adoc[] + +Basic information on creating a Maven Plugin is described in the https://maven.apache.org/plugin-developers/index.html[Maven User Guide] chapter of plugin development. + +[source, java] +---- +include::{maven-plugin-source-path}/htmlSanityCheck/htmlsanitycheckmavenplugin/HtmlSanityCheckMojo.java[tag=maven-plugin-implementation] +---- + + +==== Directory Structure and Required Files + +To be dome //todo + +==== Passing Parameters From Buildfile to Plugin +To be done + +==== Building the Plugin + +The plugin code itself is built with maven. + +==== Uploading to Public Archives + +TBD + +==== Further Information on Creating Maven Plugins + +The https://maven.apache.org/plugin-developers/index.html[Maven user guide] describes how to write a plugins. diff --git a/src/docs/development/development-intro.adoc b/src/docs/development/development-intro.adoc index 1ef353ce..ac7a0ce3 100644 --- a/src/docs/development/development-intro.adoc +++ b/src/docs/development/development-intro.adoc @@ -18,12 +18,13 @@ Make yourself familiar with -* The https://gradle.org[Gradle] build system, +* The{gradle-url}[Gradle] build system, +* the {maven-url}[Maven] build system, * https://jsoup.org/apidocs/[JSoup API documentation]. ==== Prerequisites for Gradle Plugin Development -You should definitely read the original https://www.gradle.org/docs/current/userguide/custom_plugins.html[Gradle Plugin Development Guide] on custom plugin development. +You should definitely read the original https://www.gradle.org/docs/current/userguide/custom_plugins.html[Gradle Plugin Development Guide] and the https://maven.apache.org/plugin-developers/index.html[Maven User Guide] on custom plugin development. === Adding New Checks @@ -82,3 +83,7 @@ by making $MODULE_DIR$ your default. image:intellij-run-configuration.jpg[] +==== Maven Plugin + +To be done //todo + diff --git a/src/docs/manual/01_maven-plugin.adoc b/src/docs/manual/01_maven-plugin.adoc new file mode 100644 index 00000000..3a3b0115 --- /dev/null +++ b/src/docs/manual/01_maven-plugin.adoc @@ -0,0 +1,10 @@ +:filename: manual/01_maven-plugin.adoc +:imagesdir: ../images +:jbake-menu: Manual +:jbake-order: 30 +:jbake-title: HTML Sanity Check (Maven Plugin) + +ifndef::projectRootDir[:projectRootDir: ../../..] +:xrefToManual: 01_manual.adoc + +include::{projectRootDir}/htmlSanityCheck-maven-plugin/README.adoc[leveloffset=+1] \ No newline at end of file diff --git a/src/docs/plantuml/whitebox-hsc-core-level-2.puml b/src/docs/plantuml/whitebox-hsc-core-level-2.puml index 8a26cac7..aa4221fc 100644 --- a/src/docs/plantuml/whitebox-hsc-core-level-2.puml +++ b/src/docs/plantuml/whitebox-hsc-core-level-2.puml @@ -35,6 +35,8 @@ checker -->reporter checker --> suggester checker -left-> futil checker -> netutil +checker -down-> files +checker -down-> web suggester -left-> files @@ -46,8 +48,12 @@ netutil -down-> web [HSC Gradle Plugin] as gradleplugin gradleplugin -down-> config gradleplugin -down-> acr -checker -down-> web -checker -down-> files + +[HSV Maven Plungin] as mavenplugin +mavenplugin -down-> config +mavenplugin -down-> acr + + -@enduml \ No newline at end of file +@enduml diff --git a/src/docs/plantuml/whitebox-hsc-level-1.puml b/src/docs/plantuml/whitebox-hsc-level-1.puml index 53d33cac..350b40db 100644 --- a/src/docs/plantuml/whitebox-hsc-level-1.puml +++ b/src/docs/plantuml/whitebox-hsc-level-1.puml @@ -23,12 +23,12 @@ rectangle "HtmlSanityCheck (Level 1)" as HSC { [HSC Graphical UI] <> as ui -[HSC Maven Plugin] <> as mavenplugin +[HSC Maven Plugin] as mavenplugin [FileUtil] as futil [NetUtil] as netutil -mavenplugin .down-> core +mavenplugin -down-> core ui .down-> core core -> futil @@ -44,7 +44,7 @@ netutil -down-> web bs -down-> [HSC Gradle Plugin] -bs .down.> mavenplugin +bs -down-> mavenplugin core -down-> files core -down-> web