Expansion Diff Tooling

The expansion-normalizer is a tool to compare the results of 2 different expansions. The tool will process all files in an expansion directory and remove non-functional variations such as comments. The result is a file that is easier to compare when looking for functional changes.

Setup

The current version of the normalizer is 1.1.1. The jar can be found in the nexus repository:

Donwload link: expansion-normalizer-1.1.1.jar

the expansion-normalizer requires jre 1.8 to run

Usage

To run the normalizer use the following command:

java -jar expansion-normalizer-1.1.1.jar <expansionDirectory> <targetDirectory> [<includePattern> [<excludePattern>]]

This will generate a normalized copy of the project in the target directory, including and excluding files based on the provided patterns.

The patterns are based on a glob syntax:

  • ‘*‘ or ‘all’ will include every file

    In Unix systems, it is possible to use ‘*’ to match everything. However, in windows this creates unexpected behaviour, using ‘all’ is recommended in this case.

  • ‘Agent.java’ will only normalize files containing ‘Agent.java’, such as UserAgent.java

  • ‘data,logic’ will include all paths that contains logic or data

The exclude pattern will exclude all files that match the includePattern, but also the exclude pattern.

E.g. java -jar expansion-normalizer-1.1.jar x y * client will include all files except for the files in the client layer.

How it works

The normalizer will use a number of methods to reduce differences between files, depending on the file type:

  • remove comments
  • reorder methods in a deterministic order
  • fix indent of each line and trim trailing whitespace -

JavaScript normalizer

The expansion-normalizer does not correct the indent of js files. For this, it is possible to install js-beautify with npm and run the following (bash) script:

readonly JS_BEAUTIFY="js-beautify --quiet --indent-size 2 --replace"
find "$TARGET_DIR" -name '*.js' -print0 | xargs --no-run-if-empty -0 $JS_BEAUTIFY