Chapter 12. 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 - similar to a newspaper versus a whole encyclopedia. This delta feature is currently implemented in our Open Source project "Sonargraph Integration Access" that is hosted on GitHub at https://github.com/sonargraph/sonargraph-integration-access.

This 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>
        

If reports are generated at the beginning and end of a feature implementation, this delta log provides a quick overview about changes related to Sonargraph issues and how the overall state of the system has been improved.

The delta report can be generated by specifying a previously generated XML report file as a baseline. The delta report is a plain text file. 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 delta 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 groups issues 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 script or an architecture file is renamed, the origin of the issues generated by those resources is changed.

  3. 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.

Ideas for feature improvements are to include the baseline report as filter in Sonargraph Architect/Explorer to let the user focus on changed issues.