Skip to content

Advanced setup

Jump to bottom
Silvio Montanari edited this page Sep 16, 2019 · 8 revisions

This section describes additional, custom settings you can apply to code-forensics to help you make it work for what you need.

Such configuration options are expected to be expressed in a JSON file named .code-forensics placed in your project directory, where you installed the npm package. Some can also be passed via the command line as environment variables.

Version control system

This option configures what type of VCS code-forensics expects to use. Two types of VCS are currently supported:

  • git (default)
  • subversion

The behaviour of code-forensics will change depending on what version control system is in use for a given repository, see Version control support for more information.

example setup: use subversion instead of git
{
  "versionControlSystem": "subversion"
}

JavaScript parser options

code-forensics uses the typhonjs-escomplex package to produce cyclomatic complexity reports, which in turn uses babylon to parse and generate a JavaScript AST (Abstract Syntax Tree). You can define additional options to be passed to the babylon parser to enable not yet standardised ECMAScript features.

example setup: enable parsing of react JSX files
{
  "javascriptParser": {
    "options": {
      "plugins": ["jsx"]
    }
  }
}

Code Maat options

code-forensics can be configured to execute Code Maat in two ways:

  1. The default behaviour is to use the jar that is bundled within the same npm package. This will require the platform to have a Java runtime installed. It is also possible to instruct code-forensics to use a different jar file for Code Maat if you wish to build and install it yourself.
example setup: point at a different Code Maat package
{
  "codeMaat": {
    "packageFile": "/some/path/to/code-maat-1.0-SNAPSHOT-standalone.jar"
  }
}
  1. Alternatively you may configure code-forensics to execute Code Maat through Docker. This could be a better option if you don't want to install Java and already have docker available in your platform. At the moment there doesn't seem to be an official docker image of code-maat, however its repo website provides a Dockerfile and instructions to build your own.
example setup: use a pre-built Code Maat docker image
{
  "codeMaat": {
    "docker": {
      "image": "code-maat-app:latest"
    }
  }
}
  • The image property is required.
  • An optional volume property is also configurable, which defines how to mount the data folder volume used within the code-maat docker container. code-forensics by default will mount the current working directory as a volume into the container, so that it can resolve the log file path to be passed to the code-maat command relative to such location. However, if the configured tempDir references a path location outside the directory you run code-forensics from, you should explicitly set the volume property to point at a directory that includes such folder.
example setup: use a pre-built Code Maat docker image with custom volume mapping
{
  "codeMaat": {
    "docker": {
      "image": "code-maat-app:latest",
      "volume": "<your-tempDir-or-parent-folder>"
    }
  }
}

In summary:

  • with no configuration, code-forensics will execute code-maat by running the embedded package with java.
  • with a packageFile property, code-forensics will execute code-maat by running the configured package with java.
  • with a docker configuration section, code-forensics will try to execute code-maat by running the given image with docker. This configuration takes priority over any other one.

Note: When building a custom Code Maat jar, or docker image, do stick with the same major version as the one used by code-forensics in order to minimise risks of incompatibility.

Although code-forensics handles all the interaction with Code Maat for you, you may still want to be able to pass on some options to further tune your analysis.

example setup: pass additional options to Code Maat
{
  "codeMaat": {
    "options": { "-i": 5, "-s": 100 }
  }
}

You can also configure Code Maat options via an environment variable:

$ CODEMAAT_OPTS='-i 5 -s 500' gulp <taskName>

Sloc parser options

The sloc module parser generates an error when given a file with an unrecognised extension. Although most popular programming language extensions are covered, there may be a few that would not be accepted by sloc but that could still be mapped to well known ones.

Example: Rack

Rack is a popular Ruby webserver interface that is used in many Ruby projects. Rack provides a command line tool, rackup, to quickly run a Rack application, and such command takes in a configuration file with a default ".ru" extension. That file is nothing less than a Ruby program, but sloc does not recognise its extension. If you're interested in parsing your rack configuration file as part of your cyclomatic complexity analysis (and most likely you're not) you can configure the following sloc options:

example setup: configure a specific mapping for a filename
{
  "sloc": {
    "basenameMapping": {
      "config.ru": "rb"
    }
  }
}
example setup: configure an extension mapping
{
  "sloc": {
    "extensionMapping": {
      ".ru": "rb"
    }
  }
}

Parallel vs Serial execution

This option lets you control whether analysis tasks can be run in parallel or sequentially by Node.js. Allowing too many functions to run in parallel could max out your CPU as well as create too many Event Emitters too quickly (causing NodeJS warnings).

By default code-forensics will allow concurrent tasks up to the number of available CPUs/cores, however you can force a serial processing mode which will limit that number to 1. Be aware, though, that any individual Code Maat analysis (running Clojure on Java) will likely still use multiple threads.

example setup: disable parallel execution
{
  "serialProcessing": true
}

You can also configure the serial processing mode via an environment variable:

$ SERIAL_PROCESSING=true gulp <taskName>

Server port number

The local webserver used to serve the html pages with the analysis diagrams runs by default on port 3000, but you can change it to any other available port number of your choice.

example setup: run the local webserver on a custom port
{
  "serverPort": 3010
}

You can also configure the server port number via an environment variable:

$ SERVER_PORT=3010 gulp webserver
Clone this wiki locally