Skip to content

Tasks parameters

Jump to bottom
Silvio Montanari edited this page Sep 23, 2019 · 9 revisions

Different tasks may take or require certain parameters that would affect the analysis behaviour and the generated output.

The table below describes all the possible parameters. The following sections provide a more detailed explanation

parameter name default analysis/tasks
dateFrom current date all analysis requiring a time interval
dateTo current date all analysis requiring a time interval
timeSplit undefined all analysis requiring a time interval
layerGroup undefined system analysis
targetFile undefined complexity trend or temporal coupling analysis
minWordCount 5 commit analysis
maxCoupledFiles 5 developer coupling analysis
taskName undefined help task
updateLogs false vcs log tasks

Command line parameters vs default configured parameters

Each parameter can be passed through the command line, prefixed by "--".

example:

$ gulp system-evolution-analysis --dateFrom=2015-01-01 --dateTo=2015-06-30 --timeSplit=eom

Parameters can also be configured in the gulpfile.js. This could be useful if you find yourself needing to pass the same parameter values to various tasks over and over again.

example - same time interval for different type of analysis:

require('code-forensics').configure(
  {
    // configuration options
  },
  {
    dateFrom: '2015-01-01',
    dateTo: '2015-06-30'
  }
);
Order of evaluation of parameters
  • Parameters values configured in the gulpfile.js override the program default parameters.
  • Parameters passed through the command line override any other value.

Date/Time interval of analysis

Most analyses work on version control information, and we can change the portions of the log history that we want to investigate by defining a particular time interval.

  • dateFrom: the earliest date to include repository log entries for the analysis.
  • dateTo: the latest date to include repository log entries for the analysis.

Since both parameters default to the current date, it is common to only have to define the start date of the analysis.

VCS Log files

code-forensics keeps any generated log files and attempts to re-use them across multiple analysis runs for the same given period of time. However if/when the repository configuration is modified it is recommended to re-generate the log files as their content could be incorrect.

Setting the --updateLogs flag on the command line will force the update of the log files required by the analysis being run, e.g.:

$ gulp system-evolution-analysis --updateLogs --timeSplit 1m ...

An alternative, more explicit method, is the execution of the clear-logs task, which will delete all the .log files:

$ gulp clear-logs

Time periods

Some analysis allow you to optionally aggregate/capture the results in separate time periods across the same overall interval.

  • timeSplit: defines the logic to split the time interval. Possible values are:

    • Custom time split
    Value Effect
    1d, 2d, 3d etc. Split the time interval in periods of n days starting from the initial date
    1w, 2w, 3w etc. Split the time interval in periods of n weeks starting from the initial date
    1m, 2m, 3m etc. Split the time interval in periods of n months starting from the initial date
    1q, 2q, 3q etc. Split the time interval in periods of n quarters starting from the initial date
    1y, 2y, 3y etc. Split the time interval in periods of n years starting from the initial date
    • End of period time split
    Value Effect
    eod End of calendar Day - same effect as "1d"
    eow End of calendar Week - split the time interval at the end of each week (Sundays)
    eom End of calendar Month - split the time interval at the end of each month
    eoq End of calendar Quarter - split the time interval at the end of each quarter (Mar 31, Jun 30, Sep 30, Dec 31)
    eoy End of calendar Year - split the time interval at the end of each year (Dec 31)

    If no timeSplit is defined the entire time interval is considered as one single temporal period.

Other task-specific parameters

  • layerGroup: any of the logical names defined in the layerGroups configuration option. This parameter identifies which of the configured groups to use for the analysis. See the System boundaries settings for more details. If no group is defined the entire codebase is considered as one architectural layer.
  • targetFile: a file path relative to the root of the repository. This parameter identifies a particular file/module in the repository to be the subject of the analysis.
  • minWordCount: the minimum number of occurences of any word to be included into the analysis results.
  • maxCoupledFiles: the maximum number of files to include in the coupling analysis between two authors.
  • taskName: the name of a task to request information from.
Clone this wiki locally