Generate HTML reports from Asciidoc documents including rules and embed results as tables, diagrams or CSV files.

Note
 This tutorial is written for version 1.8.0 of jQAssistant.

1. Overview

Rules (i.e. concepts and constraints) may be embedded into Asciidoc files. jQAssistant executes these rules and renders the documents to HTML with embedded results.

By default the results are represented as tables but it is possible to specify different report types:

plantuml-component-diagram

Nodes and relationships of the result are converted to a PlantUML component diagram and rendered to an SVG file.

plantuml-class-diagram

Nodes representing Java packages, classes, fields or members and their connecting relations are converted to a PlantUML class diagram which is rendered to an SVG file.

plantuml-sequence-diagram

Path structures of the result are converted to a PlantUML sequence diagrams which is rendered to an SVG file.

Note
 For rendering PlantUML diagrams Graphviz needs to be installed and the dot executable available via the system path.

Furthermore a report type may be chosen for creating a file of a dedicated format which then will be shown as link:

graphml

Similar to the plantuml-component-diagram nodes and relationships are converted to a GraphML file. This may be viewed and explored using yEd.

csv

Create a CSV file containing tabular data for further analysis in other tools.

Tip
 Usually concepts are used for creating reports as they represent your chosen design & architecture language.

For this tutorial the following project structure is going to be used:

your.project      (1)
your.project.a    (2)
your.project.b
your.project.c

  1. The root package of the project is your.project.

  2. A package located directly within the root package represents a Module. The project consists of the modules a, b and c where b and c contain Java types depending on types located in a.

The structure and the metrics of this project shall be continuously reported within each build.

2. Integrate jQAssistant Into The Build Process

The tutorial uses Apache Maven for building the project.

jQAssistant is enabled by adding the plugin to the build/plugins section of the file pom.xml.

pom.xml
<properties>
  <jqassistant.version>1.8.0</jqassistant.version>
</properties>

<build>
  <plugins>
    <plugin>
      <groupId>com.buschmais.jqassistant</groupId>
      <artifactId>jqassistant-maven-plugin</artifactId>
      <version>${jqassistant.version}</version>
      <executions>
        <execution>
          <id>default</id>
          <goals>
            <goal>scan</goal>
            <goal>analyze</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
Tip
 To verify the setup a build should be triggered using mvn verify. The build should succeed and show a console output should containing jQAssistant’s scan and analysis messages.

The rules are embedded in Asciidoc documents which are located in the folder jqassistant/:

jqassistant/index.adoc      (1)
jqassistant/module.adoc     (2)
jqassistant/metrics.adoc    (3)

  1. index.adoc: the document used for rendering by Asciidoctor, it contains include directives for both other documents.

  2. module.adoc: reports about the project’s module structure as tables, diagrams and GraphML files.

  3. metrics.adoc: rules for collecting and reporting metrics as tables and CSV documents.

Tip
 The file index.adoc is picked up by jQAssistant by default for rendering to HTML. It must contain at least one rule, usually this is a group declaration. The rendered HTML documents are located in the folder target/jqassistant/report/asciidoc.

3. Structural Reports

3.1. Tables

The file module.adoc defines concepts related to the module structure of the project and for generating reports in different representations.

A concept module:Module first adds a label Module to each child package of the root package your.project:

[[module:Module]]
[source,cypher,role=concept]
.All packages in the root package of the main artifact are labeled as `Module`.
----
MATCH
  (:Main:Artifact)-[:CONTAINS]->(root:Package)-[:CONTAINS]->(module:Package)
WHERE
  root.fqn = "your.project"
SET
  module:Module
RETURN
  module.name as Module, module.fqn as Package
ORDER BY
  module.name
----

The returned result defines two columns Module (the name of the module) and Package. As no report type is specified for this concept its result is rendered to a table containing these columns:

Resultset

3.2. Component Diagrams

The concept module:Dependencies which is based on module:Module aggregates the type dependencies to the module packages:

[[module:Dependencies]]
[source,cypher,role=concept,requiresConcepts="module:Module",reportType="plantuml-component-diagram"]
.A module depends on another module if there is a dependency of Java types between both.
----
MATCH
  (module1:Module)-[:CONTAINS*]->(t1:Type),
  (module2:Module)-[:CONTAINS*]->(t2:Type),
  (t1)-[:DEPENDS_ON]->(t2)
WHERE
  module1 <> module2
WITH
  module1, module2, COUNT(*) AS weight
MERGE
  (module1)-[dependsOn:DEPENDS_ON_MODULE]->(module2)
SET
  dependsOn.weight = weight
RETURN
  module1, dependsOn, module2
----

This concept returns the modules (module1, module2) and their dependency relations (dependsOn). The result is used for generating a component diagram by setting the reportType attribute to plantuml-component-diagram.

module component diagram
Tip
 The generated .plantuml and .svg files are located in the folder target/jqassistant/report/plantuml.

3.3. GraphML Files

If diagrams become more complex it may be useful to export them as GraphML documents. This can be achieved by setting the report type graphml as illustrated by the concept module:DependenciesGraphML:

[[module:DependenciesGraphML]]
[source,cypher,role=concept,requiresConcepts="module:Dependencies",reportType="graphml"]
.Modules and their dependencies as GraphML report.
----
MATCH
  (module:Module)
OPTIONAL MATCH
  (module)-[dependsOn:DEPENDS_ON_MODULE]->(:Module)
RETURN
  *
----

The HTML document will provide a link to the GraphML file:

Resultset
Tip
 The generated .graphml files are located in the folder target/jqassistant/report/graphml. They may be viewed using yEd. After opening a file you need to apply a layout, Layout→Hierarchical (Alt-Shift-H).
module graphml yed

By extending the result structure the GraphML reports may be used to allow an interactive drill-down from module to type level:

[[module:DependenciesGraphMLDrilldown]]
[source,cypher,role=concept,requiresConcepts="module:Module",reportType="graphml"]
.Modules and their dependencies as GraphML report with drill-down to type level.
----
MATCH
  (module:Module)-[:CONTAINS*]->(type:Type)
OPTIONAL MATCH
  (type)-[dependsOn:DEPENDS_ON]->(:Type)<-[:CONTAINS*]-(:Module)
RETURN
  {
    role: "graph",
    parent: module,
    nodes: collect(type),
    relationships: collect(dependsOn)
  }
----

This concept returns a graph for each module which is rendered as parent containing types (nodes) and dependencies (relationships) per module. The generated GraphML report file can be interactively explored in yEd by expanding (+) or collapsing (-) module nodes and applying the horizontal layout:

module graphml drilldown yed

3.4. Class Diagrams

Java structures returned by a rule may be rendered to class diagrams. The following elements are supported:

  • Packages (:Java:Package)

  • Types (:Java:Type)

  • Members (:Java:Member, :Java:Field, :Java:Method)

  • Inheritance relations between types (:EXTENDS, :IMPLEMENTS)

  • any other relations between types (rendered as associations)

The concept module:ClassDiagram returns all types including their optional fields and methods:

[[module:ClassDiagram]]
[source,cypher,role=concept,requiresConcepts="module:Module",reportType="plantuml-class-diagram"]
.Class Diagram
----
MATCH
  (module:Module:Package)-[:CONTAINS*]->(type:Type)
OPTIONAL MATCH
  (type)-[extends:EXTENDS|IMPLEMENTS]->(:Type)
OPTIONAL MATCH
  (type)-[:DECLARES]->(field:Field)
OPTIONAL MATCH
  (type)-[:DECLARES]->(method:Method)
RETURN
  *
----

As the report type is set to plantuml-class-diagram the following diagram is rendered and embedded into the HTML document:

module class diagram

3.5. Sequence Diagrams

A rule returning a path structure in a column named sequence can be rendered to sequence diagrams by setting the report type to plantuml-sequence-diagram:

[[module:SequenceDiagram]]
[source,cypher,role=concept,reportType="plantuml-sequence-diagram"]
.Sequence Diagram
----
MATCH
  (:Type{name:"ServiceCImpl"})-[:DECLARES]->(method:Method{name:"run"}),
  sequence=((method)-[:INVOKES*]->(:Method))
RETURN
  sequence
----

The nodes of the sequence are interpreted as participants and the relationships between them as messages. This results in the following diagram to be generated:

module sequence diagram

4. Metrics

4.1. Tables

The results of concepts or constraints are rendered to tables by default. This may be used to directly embed metrics into the HTML documents as illustrated by the concept metrics:LoCAndComplexity located in metrics.adoc:

[[metrics:Top10LoCAndCC]]
[source,cypher,role=concept]
.The top 10 types with the highest LoC (lines of code) and aggregated CC (cyclomatic complexity).
----
MATCH
  (:Artifact)-[:CONTAINS]->(type:Type)-[:DECLARES]->(method:Method)
RETURN
  type AS Type, sum(method.cyclomaticComplexity) AS CC, sum(method.effectiveLineCount) AS LoC
ORDER BY
  LoC DESC, CC DESC
LIMIT
  10
----

The HTML document will contain the following table:

metrics table

4.2. CSV Reports

It may be useful to provide metrics as a CSV files for further analysis in other tools. Fur such cases the report type csv may be specified:

[[metrics:Top10LoCAndCCAsCSV]]
[source,cypher,role=concept,reportType="csv"]
.The top 10 types with the highest LoC (lines of code) and CC (cyclomatic complexity).
----
MATCH
  (:Artifact)-[:CONTAINS]->(type:Type)-[:DECLARES]->(method:Method)
RETURN
  type AS Type, sum(method.cyclomaticComplexity) AS CC, sum(method.effectiveLineCount) AS LoC
ORDER BY
  LoC DESC, CC DESC
LIMIT
  10
----

Instead of an embedded table a link to the generated CSV file will be rendered:

metrics csv link
Tip
 Generated .csv files are located in the folder target/jqassistant/report/csv.

The file can now be imported into tools providing support for CSV files:

metrics csv sheet

5. Rules in XML files

jQAssistant rules may be located in Asciidoc or XML files. The latter are not rendered to HTML but the results of concepts and constraints can be reported in a similar way as described in the previous sections. This can be achieved by adding a <report> element with a type attribute:

jqassistant/module.xml
<jqassistant-rules xmlns="http://schema.jqassistant.org/rule/v1.8">

    <concept id="module-xml:DependenciesGraphML">
        <description>Modules and their dependencies as GraphML report.</description>
        <cypher><![CDATA[
            MATCH
              (module:Module)
            OPTIONAL MATCH
              (module)-[dependsOn:DEPENDS_ON_MODULE]->(:Module)
            RETURN
              *
        ]]></cypher>
        <report type="graphml" />
    </concept>

</jqassistant-rules>

The generated files will be located in the according sub-directories of target/jqassistant/report.

6. Resources

  1. ZIP archive including the application