Chapter 8. Reporting Changes

Reports for large systems provide an overwhelming amount of information. Most of the times a report containing the changes compared to a baseline is enough - like a newspaper versus a whole encyclopedia. From SonargraphBuild version 9.13.0 onwards, an additional system diff HTML report is generated if a baseline XML report is specified via the parameter "baselineReportPath". The full and diff reports are inter-linked.

NOTE

This functionality is only available in the commercial version of Sonargraph.

The resulting diff report contains only the changes. The following screenshot shows the top part of a sample report:

System Diff HTML Report
Figure 8.1. System Diff HTML Report


The report is divided in sections equal to the tabs of the "System Diff" view in the Sonargraph application. If the sections contain changes, this is indicated by the prefix "(!)" in the top-left navigation section.

This feature has been introduced with the Sonargraph release 9.13 and we will continue improving the precision of the results in upcoming releases. Feedback is always welcome and can be sent to .

Upcoming Improvements in Next Versions

We plan the following improvements for the next versions of SonargraphBuild to further improve the matching of issues contained in the baseline and the current system:

  • Support for XML and plain text format for the diff report to make integration of the information easy in other environments.

  • Processing of duplicate code block issues which are currently not part of the system diff.

  • Detection if a Sonargraph module is renamed.

  • Once SCM information is included in Sonargraph, the rename of script or architecture files can be detected.

  • Once SCM information is included in Sonargraph, rename of an element or one of its parents can be detected.

NOTE

As with every modification: Frequent and small changes are easier to review than big-bang refactorings.

8.1. Compute the System Delta (Deprecated)

This functionality is available in SonargraphBuild version 9.4.2 and newer. It is now deprecated and will be removed in a future release. To use the delta feature, you need to set the parameter "computeDeprecatedDelta" to "true", configure the parameter "baselineReportPath" and optionally the parameter "deltaReportPath" when creating a report.

The delta computation of two XML reports is implemented in our Open Source project "Sonargraph Integration Access" that is hosted on GitHub at https://github.com/sonargraph/sonargraph-integration-access . Thus, you can embed the report delta computation easily within your own custom build pipeline if the integration with SonargraphBuild does not satisfy your requirements. The functionality is available in Integration Access 3.0.0 and newer. It can be called with the following command-line and two mandatory arguments: The first being the baseline report and the second the XML report that is compared against the baseline. If no output file is specified as the third parameter, the info is printed to the console.

		        java -cp ../../target/sonargraph-integration-access-3.0.0.jar
		        com.hello2morrow.sonargraph.integration.access.ReportDiff
		        <path-to-baseline-report-xml> <path-to-report-xml> <optional: output-file-path> 

The delta report is currently plain text. An example report is shown below (lines have been truncated) that shows differences in issues:

Delta of System Reports:
		   Report1 (baseline): D:\00_repos\sonargraph-integration-access\src\test\diff\AlarmClockMain_01.xml
		   Report2           : D:\00_repos\sonargraph-integration-access\src\test\diff\AlarmClockMain_02.xml
		
		System Info: 
		   Name: AlarmClockMain
		   ID: 6db0a52dfa66892be8a4bc2bb7cf1720
		   Path: D:\00_repos\sonar-sonargraph-integration\src\test\AlarmClockMain\AlarmClockMain.sonargraph
		
		Delta of Systems
		   System 1 (Baseline): AlarmClockMain from Nov 30, 2016 5:01:13 PM
		   System 2           : AlarmClockMain from Dec 30, 2016 5:01:13 PM
		
		- Issue delta:    
		    Removed (13):
		        EmptyArchitectureElement, generated by Core: Artifact 'Foundation', line 1, resolved 'false'
		        Potentially dead method, generated by ./Java/BadSmells/FindDeadCode.scr: Method has ...
		        Potentially dead type, generated by ./Java/BadSmells/FindDeadCode.scr: Type has no ...
		        Duplicate Code Block with 2 occurrences, block size '52', resolved 'false'
		         Occurrence in ./com/h2m/alarm/model/AlarmClock.java, start '52', block size '52', ...
		         Occurrence in ./com/h2m/alarm/presentation/Main.java, start '34', block size '52', ...
		        JavaFileClassFileMissing, generated by JavaLanguageProvider: Missing class file for ...
		    Improved (1):
		        Previous: ThresholdViolation, generated by ./Java/BadSmells/FindDeadCode.scr: Potentially ...    
		    Worsened (1):
		        Previous: ThresholdViolation, generated by Core: Total Lines = 106 (allowed range: 0 to ...    
		    Added (6):
		        Supertype uses subtype, generated by ./Core/SuperTypeUsesSubType.scr: Reference to ...
		        ArchitectureViolation, generated by ./Layers.arc: [Local Variable] 'Model' cannot access ...        
		        

If present, the report also shows differences in the core system configuration (i.e. licensed features, active analyzers, metric provider, metric ids, etc.), workspace configuration and resolutions.

Current Limitations

The following changes only indirectly affect the Sonargraph issues, but will be treated as changes by the diff detector. The issues in the baseline report will be reported as removed and the issues from the new report as added, despite the fact that the issues are logically the same:

  1. Cycle group and duplicate code block issues consist of several parts that contribute to their unique IDs. If one of these parts changes (for example a source file has been renamed) then the issue's ID is changed.

  2. If a module or root directory is renamed, the fully qualified names of contained elements change and thus the issues changed.

  3. If a script or an architecture file is renamed, the origin of the issues generated by those resources is changed.

  4. For some issues the originating line within a source file is stored and used for comparison. Changing unrelated lines in the source file before the issue's origin therefore will cause the issue to be treated as changed.

NOTE

As with every modification: Frequent and small changes are easier to review than big-bang refactorings.