jQAssistant report plugin for rendering Asciidoc rule documents to HTML including results as tables and diagrams.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
.editorconfig
.gitignore
LICENSE
README.adoc
pom.xml

README.adoc

jQAssistant Asciidoc Report Plugin

This project provides a jQAssistant report plugin for rendering Asciidoc documents containing rules and embedding their results.

How It Works

The plugin records the results of executed rules (i.e. concepts and constraints). At the end of the analysis phase Asciidoctor is used for rendering the input documents providing the rules to HTML documents. The listings containing rules are identified and their status and results appended.

Furthermore include directives are provided for embedding a summary about executed and imported rules.

Prerequisites

  • Java 7 or higher

  • Maven 3.2.5 or higher

  • jQAssistant 1.4.0 (see below)

Setup

The plugin can be enabled in a Maven based project by adding it as a dependency to the jQAssistant Maven plugin:

pom.xml
<build>
    <plugins>
        <plugin>
            <groupId>com.buschmais.jqassistant</groupId>
            <artifactId>jqassistant-maven-plugin</artifactId>
            <version>1.4.0</version>
            <executions>
                <execution>
                    <id>default-cli</id>
                    <goals>
                        <goal>scan</goal>
                        <goal>analyze</goal>
                    </goals>
                    <configuration>
                        <failOnSeverity>MAJOR</failOnSeverity>
                        <warnOnSeverity>MINOR</warnOnSeverity>
                        <useExecutionRootAsProjectRoot>true</useExecutionRootAsProjectRoot>
                        <scanIncludes>
                            <scanInclude>
                                <path>${project.basedir}/.git</path>
                            </scanInclude>
                        </scanIncludes>
                        <reportProperties>
                            <asciidoc.report.rule.directory>${session.topLevelProject.basedir}/jqassistant</asciidoc.report.rule.directory> (1)
                            <asciidoc.report.file.include>index.adoc</asciidoc.report.file.include>                                         (2)
                        </reportProperties>
                    </configuration>
                </execution>
            </executions>
            <dependencies>
                <dependency>                                                                                                                (3)
                    <groupId>org.jqassistant.contrib.plugin</groupId>
                    <artifactId>jqassistant-asciidoc-report-plugin</artifactId>
                    <version>1.1.0</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>
  1. Defines the directory where the source Asciidoc files are located.

  2. The filter specifying the source file which should be rendered (optional).

  3. Declares the plugin as dependency for jQAssistant

Includes

The report may be enhanced by jQA include directives:

jQA:Summary[]

Summary table containing all executed rules and their state

jQA:ImportedRules[]

Descriptions for all rules which have been executed but which are not part of the document itself (i.e. provided by plugins)

jqassistant/index.adoc
= My Project

This document describes architectural and design rules for My Project.

== Summary

include::jQA:Summary[]

[[default]]
[role=group,includesGroups="..."]
== Rules

...
project specific rules
...

== Imported Rules

include::jQA:ImportedRules[]

Component Diagrams

The plugin provides supports generating component diagrams from rule results.

Note
This feature is based on PlantUML which itself relies on Graphviz. The latter needs to be installed and the dot executable must be present on the system path.

To activate diagram rendering a report property render=component-diagram must be set. The result of the rule simply needs to return all required nodes and their relationships:

jqassistant/index.adoc
[[package:DependencyDiagram]]
[source,cypher,role=concept,requiresConcepts="dependency:Package",reportType="plantuml-component-diagram"] // (1)
.Creates a diagram about dependencies between packages containing Java types (test artifacts are excluded).
----
MATCH
  (artifact:Artifact)-[:CONTAINS]->(package:Package)-[:CONTAINS]->(:Type)
WHERE
  artifact.type <> "test-jar"
OPTIONAL MATCH
  (package)-[dependsOn:DEPENDS_ON]->(:Package)
RETURN
  package, dependsOn                                                                                           // (2)
----

(1) The report type is set to plantuml-component-diagram. (2) The packages are returned as nodes and their dependencies (dependsOn) as relationships.

The result might also specify graph-alike structures which will be rendered as PlantUML folders. The following example therefore uses a modified return clause:

jqassistant/index.adoc
[[package:DependencyPerArtifactDiagram]]
[source,cypher,role=concept,requiresConcepts="dependency:Package",reportType="plantuml-component-diagram"]
.Creates a diagram about dependencies between packages containing Java types (per artifact, test artifacts are excluded).
----
MATCH
  (artifact:Artifact)-[:CONTAINS]->(package:Package)-[:CONTAINS]->(:Type)
WHERE
  artifact.type <> "test-jar"
OPTIONAL MATCH
  (package)-[dependsOn:DEPENDS_ON]->(:Package)
RETURN
  {                                   // (1)
    role : "graph",                   // (2)
    parent : artifact,                // (3)
    nodes : collect(package),         // (4)
    relationships: collect(dependsOn) // (5)
  }
----
  1. Instead of nodes and relations a map-like structure is returned

  2. role determines that the map shall be interpreted as graph containing nodes and relationships

  3. parent specifies the node that shall be rendered as folder, i.e. the container of nodes

  4. nodes are the nodes to be included in the folder

  5. relationships are the relationships between the nodes, they may reference nodes of other parents/folders

Configuration

The Asciidoc Report plugin accepts several options that might be passed as report properties to jQAssistant:

Property Description Default

asciidoc.report.directory

Specifies the directory where the HTML files will be written

jqassistant/report/asciidoc

asciidoc.report.rule.directory

Specifies the directory where the Asciidoc files are located

jqassistant/rules

asciidoc.report.file.include

A comma separated list of filter of Asciidoc files to be included (optional)

asciidoc.report.file.exclude

A comma separated list of filter of Asciidoc files to be included (optional)

Feedback

Please report any issues here.

Acknowledgements

The plugin could not provide its functionality without the support of the following open source projects: