plone.recipe.codeanalysis 1.0rc1

Introduction

plone.recipe.codeanalysis provides static code analysis for Buildout-based Python projects, including flake8, JSHint, CSS Lint, and other code checks.

This buildout recipe creates a script to run the code analysis:

bin/code-analysis

By default plone.recipe.codeanalysis also creates a git pre-commit hook, in order to run the code analysis automatically before each commit.

plone.recipe.codeanalysis comes with a Jenkins integration, that allows to use the same code analysis settings on your local machine as well as on Jenkins.

Installation

Just add a code-analysis section to your buildout.cfg:

[buildout]
parts += code-analysis

[code-analysis]
recipe = plone.recipe.codeanalysis
directory = ${buildout:directory}/src

The directory option is not required. Though, if you don’t specify a directory the code analysis will check every file in your buildout directory.

Jenkins Installation

plone.recipe.codeanalysis provides a Jenkins setting that allows to run it on a Jenkins CI server and to process and integrate the output via the Jenkins Violations plugin.

Usually you don’t want the recipe to create Jenkins output files on your local machine. Therefore it makes sense to enable the Jenkins output only on the CI machine. To do so, just create a jenkins.cfg that extends and overrides the default buildout file (that includes the other settings):

[buildout]
parts += code-analysis

[code-analysis]
recipe = plone.recipe.codeanalysis
jenkins = True

The Jenkins job itself should run “bin/code-analysis”:

python bootstrap.py -c jenkins.cfg
bin/buildout -c jenkins.cfg
bin/jenkins-test --all
bin/code-analysis

The Jenkins Violations plugin needs to be configured to read the output files generated by this configuration.

pep8 (to read the flake8 output):

**/parts/code-analysis/flake8.log

csslint:

**/parts/code-analysis/csslint.xml

jslint (to read the jshint output:

**/parts/code-analysis/jshint.xml

Links

Code repository:

https://github.com/plone/plone.recipe.codeanalysis

Continuous Integration:

https://travis-ci.org/plone/plone.recipe.codeanalysis

Issue Tracker:

https://github.com/plone/plone.recipe.codeanalysis/issues

Supported options

The recipe supports the following options:

directory

Directory that is subject to the code analysis.

pre-commit-hook

If set to True, a git pre-commit hook is installed that runs the code analysis before each commit. Default is True.

jenkins

If set to True, the flake8, jshint and csslint code analysis steps will write output files that can be processed by the Jenkins Violations plugin. Default is False.

flake8

If set to True, run Flake8 code analysis. Default is True.

flake8-ignore

Skip errors or warnings. See Flake8 documentation for error codes. Default is none.

flake8-exclude

Comma-separated filename and glob patterns default. Say you want to exclude bootstrap.py, setup.py and all collective.* and plone.* packages. Just set “flake8-exclude=bootstrap.py,docs,*.egg,setup.py,collective.*, plone.*” in your buildout configuration. Default is bootstrap.py,docs,*.egg.

flake8-max-complexity

McCabe complexity threshold. Default is 10.

flake8-max-line-length

Set maximum allowed line length. Default is 79.

jshint

If set to True, jshint code analysis is run. Default is False. Note that plone.recipe.codeanalysis requires jshint >= 1.0.

jshint-bin

JSHint executable. Default is jshint. If you have JSHint installed on your system and in your path, there is nothing to do. To install JSHint in your buildout, use the following:

[jshint]
recipe = gp.recipe.node
npms = jshint
scripts = jshint

set jshint-bin to ‘${buildout:directory}/bin/jshint’.

jshint-exclude

Allows you to specify directories which you don’t want to be linted. Default is none. If you want JSHint to skip some files you can list them in a file named .jshintignore. See JSHint documentation for more details.

jscs

If set to True, jscs code analysis is run. Default is False.

JavaScript Code Style options should be configured using a .jscs.json file. You should align your javascript code to the next generation of Plone’s javascript framework Mockup and take it’s .jscs.json file which is available here: https://github.com/plone/mockup/blob/master/.jscs.json

All configuration options are documented on the jscs website.

jscs-bin

Set the path to a custom version of JSCS, e.g. “/usr/local/bin/jscs”.

If you have Javascript Code Style Checker installed in your system and path, you have nothing to do. To install with Buildout, add the following section to your buildout and set jscs-bin to {buildout:bin-directory}/jscs:

[jscs]
recipe = gp.recipe.node
npms = jscs
scripts = jscs

jscs-exclude

Allows you to specify directories and/or files which you don’t want to be checked. Default is none. Note that these directories have to be given in absolute paths, use ${buildout:directory}/foo/bar/static/js-3rd-party for example.

csslint

If set to True, CSS Lint code analysis is run. Default is False.

CSS Lint options should be configured using a .csslintrc file. A typical .csslintrc file will look like this:

--format=compact
--quiet
--ignore=adjoining-classes,floats,font-faces,font-sizes,ids,qualified-headings,unique-headings
--exclude-list=foo/bar/static/third-party.css

This typical configuration includes a list of CSS rules that will be ignored as they are considered useless.

See CSS Lint documentation for a detailed list and description of the rules.

csslint-bin

Set the path to a custom version of CSS Lint, e.g. “/usr/local/bin/csslint”.

If you have CSS Lint installed in your system and path, you have nothing to do. To install CSS Lint with Buildout, add the following section to your buildout and set csslint-bin to {buildout:bin-directory}/csslint:

[csslint]
recipe = gp.recipe.node
npms = csslint
scripts = csslint

deprecated-aliases

For historical reasons, some of the unittest.TestCase methods had one or more aliases that are deprecated on Python 2.7. If this option is set to True, warnings about deprecated aliases will be printed. Default is False. See Unit testing framework documentation for more information.

utf8-header

If set to True, Python files without a utf-8 header (like # -*- coding: utf-8 -*-) will cause a warning. Default is False.

clean-lines

If set to True, any file containing trailing spaces or tabs anywhere on the lines will cause a warning. Default is False.

clean-lines-exclude

Allows you to specify directories and/or files which you don’t want to be checked. Default is none. Note that these directories have to be given in absolute paths, use ${buildout:directory}/foo/bar/static/js-3rd-party for example.

prefer-single-quotes

If set to True, Python files will be scanned searching for strings quoted with double quote signs ("). Default is False.

pep3101

If set to True, Python files will be scanned in search of existing ‘%’ string formatting operators. Default is False. See PEP 3101 (Advanced String Formatting) for more information.

imports

If set to True, checks that imports in Python files follow plone.api conventions. This also includes checking for alphabetically sorted import statements. Default is False.

debug-statements

If set to True, scan Python files looking for debug-like statements. Default is False.

return-status-codes

If set to True, the bin/code-analysis script returns an error code that Continuous Integration servers (like Travis CI) can use to fail or pass a job, based on the code analyis output. Note that Jenkins usually does not need this option (this is better handled by the Jenkins Violations plugin). Note that this option does not have any effect on the other code analysis scripts. Default is False.

Known Issues

JSHint “ERROR: Unknown option –verbose”:

JSHint                [ OK ]
ERROR: Unknown option --verbose

Upgrade JSHint to latest version (>= 1.0) to fix this issue, e.g.:

$ sudo npm install -g jshint

JSHint “ERROR: Unknown option –exclude”:

JSHint                [ OK ]
ERROR: Unknown option --exclude

Upgrade JSHint to latest version (>= 2.1.6) to fix this issue, e.g.:

$ sudo npm install -g jshint

Example usage

Minimal buildout:

>>> write('buildout.cfg',
... """
... [buildout]
... parts = code-analysis
...
... [code-analysis]
... recipe = plone.recipe.codeanalysis
... directory = %(directory)s
... """ % {
...     'directory' : '${buildout:directory}/plone/recipe/codeanalysis',
... })

Running the buildout gives us a ‘code-analysis’ script that runs the entire code analysis:

>>> buildout_output_lower = system(buildout).lower()
>>> '/sample-buildout/bin/code-analysis' in buildout_output_lower
True

It is also possible to run single code analysis scripts:

>>> '/sample-buildout/bin/code-analysis-flake8' in buildout_output_lower
True
>>> '/sample-buildout/bin/code-analysis-jshint' in buildout_output_lower
True

Flake 8 is installed by the buildout script, there is no need to install it on the system:

>>> '/sample-buildout/bin/flake8' in buildout_output_lower
True

Deprecated aliases analysis script is installed:

>>> '/sample-buildout/bin/code-analysis-deprecated-aliases' in buildout_output_lower
True

The script to check if python files have an utf-8 encoding header is installed:

>>> '/sample-buildout/bin/code-analysis-utf8-header' in buildout_output_lower
True

The script to warn about trailing spaces or tabs on files is installed:

>>> '/sample-buildout/bin/code-analysis-clean-lines' in buildout_output_lower
True

Double quotes checker script is installed:

>>> '/sample-buildout/bin/code-analysis-prefer-single-quotes' in buildout_output_lower
True

The script to check for old style string formatting is installed:

>>> '/sample-buildout/bin/code-analysis-pep3101' in buildout_output_lower
True

The script to check for plone.api style imports is installed:

>>> '/sample-buildout/bin/code-analysis-imports' in buildout_output_lower
True

The script to check for debug-like statements in python code is installed:

>>> '/sample-buildout/bin/code-analysis-debug-statements' in buildout_output_lower
True

The script to check for untranslated strings in templates is installed:

>>> '/sample-buildout/bin/code-analysis-find-untranslated' in buildout_output_lower
True

By default a git pre-commit hook is installed. Though, this does not work if the current directory is not a git repository:

>>> 'unable to create git pre-commit hook, this does not seem to be a git repository' in buildout_output_lower
True

If we have a git repository:

>>> import subprocess
>>> subprocess.call(['mkdir', '-p', '.git/hooks'])
0

And run buildout again:

>>> buildout_output_lower = system(buildout).lower()

Then the git pre-commit hook has been installed:

>>> 'install git pre-commit hook.' in buildout_output_lower
True

Contributors

• Timo Stollenwerk, Original Author

• Gil Forcada

• Héctor Velarde

• Ramiro Batista da Luz

• Daniel Widerin

Change history