- NOTE
-
This project has been archived and is no longer actively developed. Please refer to the existing releases and documentation.
The project provides a jQAssistant plugin for providing a dashboard, which shows interactive graphics about different metrics of your system. This allows you to have a quick overview about dependencies inside your project, statistics about your contributors, potential problems in your architecture and more.
The plugin provides a set of concepts, which are applied by jQAssistant, to enable the dashboard to function. The dashboard itself will then be served as a React App under a certain URL (see How To Use It)
Currently the dashboard provides:
-
An overview page, which shows different metrics as numbers
-
A structure diagram, which enables you to interactively explore your code base
-
The distribution of file types, represented by a pie chart
-
A dependency diagram, which shows you internal dependencies of your project
-
An activity dashboard, that presents different statistics about the frequency and authors of the commits
-
A knowledge distribution, showing what contributor uses what programming languages
-
A hotspot diagram, that indicates potential risks in your code
-
A test coverage diagram
You can use the plugin with Maven or with the Command Line Distribution of jQAssistant.
The plugin can be enabled in a Maven based project by adding it as a dependency to the jQAssistant Maven plugin:
<build>
<plugins>
<plugin>
<groupId>com.buschmais.jqassistant</groupId>
<artifactId>jqassistant-maven-plugin</artifactId>
<version>1.9.0</version>
<executions>
<execution>
<id>default-cli</id>
<goals>
<goal>scan</goal>
<goal>analyze</goal>
</goals>
<configuration>
<!-- Add jqassistant-dashboard:Default as a jQA group-->
<groups>
<group>jqassistant-dashboard:Default</group>
<!-- Insert your own group references here -->
</groups>
<!-- Include .git folder path as a scan location -->
<scanIncludes>
<scanInclude>
<path>${project.basedir}/.git</path>
</scanInclude>
<!-- OPTIONAL (1)-->
<scanInclude>
<path>## Path where yout pmd.xml is generated##/pmd.xml</path>
</scanInclude>
<!-- OPTIONAL (2) -->
<scanInclude>
<path>## Path where your jacoco.xml is generated ##</path>
</scanInclude>
</scanIncludes>
<!-- OPTIONAL (2) -->
<scanProperties>
<jqassistant.plugin.jacoco.filename>jacoco.xml</jqassistant.plugin.jacoco.filename>
<jqassistant.plugin.jacoco.dirname>## Path where your jacoco.xml is generated ##</jqassistant.plugin.jacoco.dirname>
</scanProperties>
</configuration>
</execution>
</executions>
<!-- Add the jqassistant-dashboard-plugin itself as a dependency-->
<dependencies>
<dependency>
<groupId>org.jqassistant.contrib.plugin</groupId>
<artifactId>jqassistant-dashboard-plugin</artifactId>
<version>1.9.0</version>
</dependency>
</dependencies>
</plugin>
<!-- OPTIONAL (1) (this is an example, your configuration may vary) -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<version>3.10.0</version>
<executions>
<execution>
<goals>
<goal>pmd</goal>
</goals>
<phase>package</phase>
</execution>
</executions>
</plugin>
<!-- OPTIONAL (2) (this is an example, your configuration may vary) -->
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.5</version>
<executions>
<execution>
<id>pre-unit-test</id>
<goals>
<goal>prepare-agent</goal>
</goals>
<configuration>
<destFile>${project.build.directory}/coverage-reports/jacoco.exec</destFile>
<propertyName>surefireArgLine</propertyName>
</configuration>
</execution>
<execution>
<id>post-unit-test</id>
<phase>test</phase>
<goals>
<goal>report</goal>
</goals>
<configuration>
<dataFile>${project.build.directory}/coverage-reports/jacoco.exec</dataFile>
<outputDirectory>${project.reporting.outputDirectory}/jacoco</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>It is possible to install the following optional plugins:
-
PMD (example configuration is shown above)
-
JaCoCo (example configuration is shown above)
Note that in order to be installed properly, you need to insert every corresponding Tag (and all its children) after the "OPTIONAL (*)" comments.
After building the project (e.g. with mvn clean install), you need to start the jQAssistant server with
mvn jqassistant:server
If the server started successfully, you can reach the dashboard under
Note, that the regular Neo4j Browser is still available (http://localhost:7474/browser/).
To enable the plugin with the Command Line Distribution, download the JAR file from Maven Central and put it in the /plugins folder from the distribution.
In addition to that, you need to install the jQA Git Plugin.
To start the jQA server run the following commands: (xxx.jar is your project build)
Linux:
sh bin/jqassistant.sh scan -f .../xxx.jar sh bin/jqassistant.sh scan -f .../.git/ sh bin/jqassistant.sh analyze -groups jqassistant-dashboard:Default sh bin/jqassistant.sh server
Windows:
bin\jqassistant.cmd scan -f ...\xxx.jar bin\jqassistant.cmd scan -f ...\.git\ bin\jqassistant.cmd analyze -groups jqassistant-dashboard:Default bin\jqassistant.cmd server
It is possible to change the underlying queries behind the different views. The following represents an example of how to accomplish that, by changing the query of the dependency diagram, so that only dependencies between top level packages (here called components) are displayed.
We will do that the regular jQAssistant way, by creating an AsciiDoc File, which contains our concept:
/jqassistant/structure.adoc
[[structure]]
[role=group,includesConcepts="structure:*"]
== Structure
=== Concepts
[[structure:Component]]
[source,cypher,role=concept,requiresConcepts="structure:RootPackage"]
.Every package that is a direct child of the root package is a `Component`.
----
MATCH
(artifact:Main:Artifact)-[:CONTAINS]->(root:Package)-[:CONTAINS]->(component:Package)
WHERE
root.fqn="org.junit"
SET
component:Component
RETURN
component.name as Component
ORDER BY
Component
----
[[structure:ComponentDependency]]
[source,cypher,role=concept,requiresConcepts="structure:Component"]
.A component depends on another component (`DEPENDS_ON_COMPONENT`) if exists at least one dependency of contained Java types.
----
MATCH
(c1:Component)-[:CONTAINS*]->(t1:Type),
(c2:Component)-[:CONTAINS*]->(t2:Type),
(t1)-[:DEPENDS_ON]->(t2)
WHERE
c1 <> c2
WITH
c1, c2, count(t2) as weight
MERGE
(c1)-[d:DEPENDS_ON_COMPONENT]->(c2)
SET
d.weight = weight
RETURN
c1 as Component, c2 as Dependency, weight as Weight
ORDER BY
Component, Weight desc
----and the index.adoc, which contains our default group:
/jqassistant/index.adoc
:toc: left
= MyProjectName
This document contains rules which are executed by https://jqassistant.org[jQAssistant]
[[default]]
[role=group,includesGroups="structure"]
== Default Rules
The following groups are executed by default:
- <<structure>>
include::structure.adoc[]You need to insert the following at its designated inside the pom.xml place (see How To Use It)
<group>default</group>For that you need to go to Architecture/Dependencies on the dashboard site. After that you can toggle the expert view on the top right corner of the diagram window. Replace the query with the following:
MATCH
(dependent_package:Component)-[d:DEPENDS_ON_COMPONENT]-(dependency_package:Component)
WHERE
dependent_package <> dependency_package
WITH
dependent_package.fqn as dependent, dependency_package.fqn as dependency, d.weight as dependencies
RETURN
dependent , dependency, dependencies
ORDER BY
dependent, dependencyTo run the query click on the "Send" button. You should see the result immediately.
The plugin could not provide its functionality without the support of the following open source projects: