lizard-monitor

Tool using the terryyin/lizard library to generate code quality metrics for several repositories

usage

usage: lizard-mon.py [-h] [--path PATH] [-v]

utility for applying the lizard.py analysis tools to git repositories
automatically

optional arguments:
  -h, --help   show this help message and exit
  --path PATH  directory to pretend lizard-mon.py was invoked from
  -v           level of verbosity

verbosity

• verbosity 0 (default): results printed to CLI for each target and overall aggregate
• verbosity 1 (-v): as above, but results also printed for each file scanned in each target
• verbosity 2 (-vv): as above, but each function that violates the limits is printed with violation reasons

installation

TODO: I'm not very experienced at distributing python applications, so for now see a very technical approach below:

• have python installed (tested with 3.6 only) and pipenv
• clone this repo git clone https://github.com/omaskery/lizard-monitor.git
• install dependencies pipenv install
• supposing the directory with your lizard-mon.yml is at /your/dir/path/:
• invoke lizard-monitor pipenv run python lizard-mon.py --path /your/dir/path/
• console output should be as expected, find output files in /your/dir/path/

example

configuration file

In a new or empty directory, create a lizard-mon.yml file with the following contents:

lizard-monitor:
  repo:
    url: https://github.com/omaskery/lizard-monitor.git
    branch: master
  analysis:
    languages:
    - python
    limits:
      ccn: 15
      lines: 100
      parameters: 10

This specifies a single target (lizard-monitor), whose code is cloneable from this github repository URL, and we're interested in the master branch. The target will be analysed for python code, with the following thresholds:

• The cyclomatic complexity number of any function should be less than or equal to 15
• The line count of any function should be less than or equal to 100
• The parameter count of any function should be less than or equal to 10

invoking

Then, assuming you have lizard-monitor installed and on the path, run the following in the directory with lizard-mon.yml:

lizard-mon

lizard-monitor will find lizard-mon.yml in the current directory, ingest information about its targets, clone each one and analyse them for any limit violations.

In this example, the repository at https://github.com/omaskery/lizard-monitor.git will be cloned to ./repos/lizard-monitor (all repositories are cloned to <directory with lizard-mon.yml>/repos/<target name>).

console output

The following output will be emitted to console:

lizard-mon (https://github.com/omaskery/lizard-monitor.git):
  cloning 'lizard-mon' for first time from: https://github.com/omaskery/lizard-monitor.git
  running analysis on C:\Users\omask\Documents\code\lizard-monitor\test-dir\repos\lizard-mon
  results for this repo: [violations: 0, NLOC=327]
overall results: [violations: 0, NLOC=327]

file outputs

Three new files will appear next to lizard-mon.yml:

• previous-results.yml
• differences.yml
• history.ndjson

previous-results.yml

This file describes the number of lines of code and number of limit violations at varying levels of granularity. Using the example from the invocation above:

overall:
  lines_of_code: 327
  violation_count: 0
targets:
  lizard-mon:
    files:
      repos\lizard-mon\lizard-mon.py:
        lines_of_code: 236
        violation_count: 0
      repos\lizard-mon\lizard_mon\__init__.py:
        lines_of_code: 2
        violation_count: 0
      repos\lizard-mon\lizard_mon\config.py:
        lines_of_code: 87
        violation_count: 0
      repos\lizard-mon\lizard_mon\exceptions.py:
        lines_of_code: 2
        violation_count: 0
    overall:
      lines_of_code: 327
      violation_count: 0

Notice that it shows the lines of code and violation count across all targets, then for each target, then for each file scanned for that target.

differences.yml

This file is generated by subtracting the current results from the previous contents of previous-results.yml. If following the example, this file will be identical to previous-results.yml because there were no previous results - so the delta will assume 0 for all previous counts.

Normally, however, if run on a project that has changed: the values would represent the change in lines of code or number of violations since the last invocation.

history.ndjson

This file is a record of previous results as new-line delimited JSON, at a high level of granularity, suitable for transforming into graphable data to observe trends. If following the example, this will contain only one entry:

{"timestamp": "2018-08-25T22:14:56.098231", "overall": {"violation_count": 0, "lines_of_code": 327}, "targets": {"lizard-mon": {"violation_count": 0, "lines_of_code": 327}}}