plone.recipe.codeanalysis provides static code analysis for Buildout-based Python projects, including flake8, JSHint, CSS Lint, zptlint, 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.
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.
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
Code repository:
Continuous Integration:
Issue Tracker:
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.- 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
- zptlint
If set to True, zptlint code analysis is run. Default is
False
.Note that the buildout itself already depends on zptlint, so no extra configuration is needed.
- zptlint-bin
Set the path to a custom version of zptlint. Default is
bin/zptlint
.- 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 isFalse
.- clean-lines
If set to True, any file containing trailing spaces or tabs anywhere on the lines will cause a warning. Default is
False
.- prefer-single-quotes
If set to True, Python files will be scanned searching for strings quoted with double quote signs (
"
). Default isFalse
.- 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. 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 isFalse
.- find-untranslated
If set to True, scan Zope templates to find untranslated strings. Default is
False
.- i18ndude-bin
Set the path to a custom version of i18ndude. Default is
bin/i18ndude
.
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":
Upgrade JSHint to latest version (>= 2.1.6) to fix this issue, e.g.:
$ sudo npm install -g jshint