Configuration

Configuration options

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

option name	required	type	default	tasks
tempDir	optional	string	'./tmp'	all
outputDir	optional	string	'./output'	all
dateFormat	optional	string	'YYYY-MM-DD'	all analyses requiring a date interval
repository.rootPath	mandatory	string	undefined	all
repository.includePaths	optional	array	[]	all
repository.excludePaths	optional	array	[]	all
languages	optional	array	['javascript']	complexity analysis
layerGroups	optional	object	{}	system analysis
contributors	optional	array/object	[]	social analysis
commitMessageFilters	optional	array	[]	commit analysis

Working directories

code-forensics tasks may produce intermediate reports to be used later for another analysis. Such files will be saved into a temporary folder, different from the output folder where the final analysis reports are published.

• tempDir: optional. path to the temporary folder.
• outputDir: optional. path to the output folder.

example:

require('code-forensics').configure(
  {
    // other options
    tempDir: './temp',
    outputDir: './artifacts'
    // other options
  }
);

Repository

The repository configuration options allow you to select which files in your repository will be considered for the analysis.

• rootPath: mandatory. It must represent an existing directory in the file system.
• includePaths: optional. includePaths can be used to restrict the analysis only to some directories/files.
• excludePaths: optional. use excludePaths to exclude some particular files/folders from the analyisis (e.g. media files, local database files and/or binaries).

Both includePaths and excludePaths can be expressed as an array of strings, and each string should be a path relative to the root of the repository. Glob expressions are also accepted.

If no includePaths or excludePaths are provided, code-forensics will scan every file under the repository root directory for analysis.

example:

require('code-forensics').configure(
  {
    // other options
    repository: {
      rootPath: '/some/path-to-the/repo',
      includePaths: [
        'app',
        'frontend',
        'config',
        'tests'
      ],
      excludePaths: [
        'app/frontend/lib',
        'app/assets/fonts',
        'app/frontend/node_modules',
        'config/db',
        '**/+(*.jpg|*.png|*.gif)'
      ]
    }
    // other options
  }
);

Languages

The languages option instructs code-forensics to detect files written in a particular programming language. This can be used to perform cyclomatic complexity analysis using appropriate tools for each specific language.

• languages: optional. An array of programming language names. Currently the only supported languages are javascript and ruby. See Cyclomatic complexity support for more information.

example:

require('code-forensics').configure(
  {
    // other options
    languages: ['ruby', 'javascript'],
    // other options
  }
);

System boundaries

For some analysis it can be useful to partition and aggregate the results based on which architectural group/layer each code file belongs to. This feature can provide valuable insights on how different parts of your system evolve in time.

• layerGroups: optional. An object containing the definitions of the architectural layers of the system grouped by a logical name. The name is descriptive of the way you intend to partition/slice your architectural view.

Each definition contains a list of expressions that identify the files in the repository included in the layer. An expression can be:

• a string corresponding to a path in the repository (relative to the repository root folder). If the path corresponds to a folder then all files and subdirectories in that folder will be included. Note: glob expressions are not valid, if you need to filter in/out specific paths use a regular expression.
• a regular expression that will be matched against every file path used in the analysis.

example:

require('code-forensics').configure(
  {
    // other options
    layerGroups: {
      'code-test': [
        { name: 'Code', paths: ['app', 'lib', 'frontend'] },
        { name: 'Unit Tests', paths: [/tests\/.*[._]spec\..*/] },
        { name: 'E2E Tests', paths: ['cucumber'] }
      ],
      'mvc-layers': [
        { name: 'Models', paths: [/^app\/\.*models/, /^frontend\/\.*models/] },
        { name: 'Controllers', paths: ['app/controllers'] },
        { name: 'Views', paths: [/^app\/views\/.+\.html$/, 'app/assets'] }
      ]
    }
    // other options
  }
);

Developers and Teams

A number of analyses are aimed at identifying the coupling between code and developers (ownership) or the dependencies (communication links) between developers working on the same code.

In code-forensics it's possible to consolidate repository usernames and their aliases under a unique name, to correctly identify the author of each commit. It is also possible to group authors under a logical name that could represent a particular team of developers.

• contributors: optional. This property accepts either an array of authors or an object that defines each team and its array of authors. An author is in turn defined through an array, with the first item representing the main username, followed by its possible aliases.

example - simple authors configuration (no teams):

require('code-forensics').configure(
  {
    // other options
    contributors: [
      ['Owen Chapman'], ['Katherine Piper', 'kpiper'], ['Jane May', 'jane', 'jmm'], ['William Mackay'], ['Diane Knox', 'the_knox']
    ]
    // other options
  }
  );

example - teams and authors configuration:

require('code-forensics').configure(
  {
    // other options
    contributors: {
      'Team Red': [['Owen Chapman'], ['Katherine Piper', 'kpiper']],
      'Team Blue': [['Jane May', 'jane', 'jmm'], ['William Mackay'], ['Diane Knox', 'the_knox']]
    }
    // other options
  }
);

Commit messages

When analysing revision messages it's often useful to filter out words or expressions that are part of the common language and not relevant to understand the key concept behind a code commit.

• commitMessageFilters: optional. An array of expressions that evaluate whether the current word is to be filtered out or not. Each array item can be:
  • a string (the exact word is not captured)
  • a regular expression. The word is not captured if the regular expression matches.
  • a function. The word is not captured if the function returns true;

example:

require('code-forensics').configure(
  {
    // other options
    commitMessageFilters: [
      /^Merge pull request/,
      /^Merge branch/,
      /\d+/,
      'and', 'the', 'for', 'from', 'with', 'not', 'has', 'when', 'where',
      function(word) { return word.length <= 2; }
    ]
    // other options
  }
);