jqassistant-archive/jqassistant-asciidoc-report-plugin

jQAssistant report plugin for rendering Asciidoc rule documents to HTML including results as tables and diagrams.

jQAssistant Asciidoc Report Plugin

Table of Contents

• How It Works
• Prerequisites
• Setup
• Includes
• Component Diagrams
• Configuration
• Feedback
• Acknowledgements

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

Note	This repository has been archived as the plugin has been integrated into the jQAssistant main project: https://github.com/jQAssistant/jqa-asciidoc-report-plugin.

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.

Tip	You can find an example setup and rules in the Spring PetClinic demo. After cloning the repository and building using mvn install the rendered report is available in the directory target/jqassistant/report/asciidoc.

Prerequisites

• Java 8 or higher

• Maven 3.2.5 or higher

• jQAssistant 1.6.0

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.6.0</version>
            <executions>
                <execution>
                    <id>default-cli</id>
                    <goals>
                        <goal>scan</goal>
                        <goal>analyze</goal>
                    </goals>
                    <configuration>
                        <!--
                        <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.6.0</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

1. Defines the directory where the source Asciidoc files are located (optional).

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

3. Declares the plugin as dependency for jQAssistant

For using the plugin with the command line distribution download the JAR file from Maven Central and copy it to the plugins/ folder.

Note	By default all rule files with the name index.adoc will be selected for rendering. The report properties asciidoc.report.rule.directory and asciidoc.report.file.include may be used to explicitly select files.

Includes

The report may be enhanced by jQA include directives:

jQA:Summary[]

Embeds a summary table containing all executed rules, their description and status.

jQA:ImportedRules[]

Renders 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 the report type must be set to plantuml-component-diagram. 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:Main:Artifact)-[:CONTAINS]->(package:Package)-[:CONTAINS]->(:Type)
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:Main:Artifact)-[:CONTAINS]->(package:Package)-[:CONTAINS]->(:Type)
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 (optional)
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 excluded (optional)
asciidoc.report.plantuml.format	Specifies the output file format of the generated PlantUML-Diagrams (optional)	SVG
asciidoc.report.plantuml.rendermode	Specifies the renderer used for the generated PlantUML-Diagrams, currently supporting GraphViz and Jdot (optional)	GRAPHVIZ

Feedback

Please report any issues here.

Acknowledgements

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

• Asciidoctor

• PlantUML

• Neo4j

• jQAssistant

jqassistant-asciidoc-report-plugin's Issues

asciidoc.report.rule.directory without asciidoc.report.file.include

If one specifies a rule-directory without specifying an include-file and the given directory contains other directories the build fails with following exception:

com.buschmais.jqassistant:jqassistant-maven-plugin:1.6.0:analyze failed: (Errno::EACCES)

The root of this problem are the following lines in AsciidocReportPlugin.java 163 ff.

ruleDirectory.listFiles(new FilenameFilter() {
     @Override
     public boolean accept(File dir, String name) {
           return filePatternMatcher.accepts(name);
      }
 })

listFiles also returns directories. Using a FileFilter and checking for file.isFile() would fix this issue.

Adding unit tests for this seems to be non-trivial otherwise i would have submitted a PR

Plugin does not work with CLI distribution due to CL problem

Asciidoctor/JRuby cannot load the IncludeProcessor as the wrong classloader is used, should be the PluginClassloader.

Release 1.7

Is there a timeline/roadmap for the 1.7 release?

Import of existing concepts and constraints into specific asciidoc

When documenting design decisions and structures, the use case can occur that already written down concepts or constraints (e.g. coming from the spring or ddd plugin) shall be referenced including the rendering of the query and results.

For that, I propose to implement an include-mechanism based on the id of a concept/constraint, e.g.

include::jQA:Rule[id="java-ddd:IllegalDependenciesBetweenBoundedContexts"]