CodeNarc plugin

Tags: quality, metrics, grails2.4
Latest: 1.0
Last Updated: 12 September 2017
Grails version: 2.4 > *

Authors: Chris Mair, Burt Beckwith, Peter Ledbrook
License: Apache License 2.0

21 votes

10% of Grails users

Dependency:

compile "org.grails.plugins:codenarc:1.0"

Documentation Source Issues

Summary

Runs CodeNarc static analysis rules for Groovy source.

Installation

Grails 3.x

Do not use this Grails Plugin. Instead, use the Gradle CodeNarc Plugin. Also see CodeNarc Support for Grails 3.x

Grails 2.x

Add

build ":codenarc:1.0"

to plugins in "BuildConfig.groovy".

Grails 1.x

Run the 'install-plugin' Grails script, e.g.

grails install-plugin codenarc

Description

CodeNarc Plugin

The CodeNarc Plugin provides static code analysis for Groovy code. It uses the CodeNarc library.

NOTES:

See GitHub Issues for this plugin.
For Grails 3.x, do not use this Grails Plugin. Instead, use the Gradle CodeNarc Plugin. See issue #8.
Version 1.0 and later of this plugin requires Groovy 2.3, which implies it is compatible only with Grails 2.4.0 or later. (So Grails version >= 2.4 and < 3.x).
Version 0.23 and later of this plugin requires Grails 2.3.0 or later. (Earlier 2.x versions may work, but no guarantees).
As of version 0.17 of this plugin, the default CodeNarc report file is now written to the "target" folder of the Grails project.
Version 0.8 and later of this plugin requires Groovy 1.7, so it cannot be used by projects on older versions of Grails (before Grails 1.3). For those projects, stay with version 0.7 of this plugin.
As of version 0.14 of this plugin, the CodeNarc plugin configuration has moved from "Config.groovy" to "BuildConfig.groovy". See below for configuration details.

Execution

The plugin provides a script 'codenarc' that will analyze your code and write its results to an HTML file. Run

grails codenarc

to perform the analysis.

Default Configuration

The plugin requires no customization to run. By default it will analyze all Groovy files in

src/groovy
grails-app/controllers
grails-app/domain
grails-app/services
grails-app/taglib
grails-app/utils
test/unit
test/integration

and use a default title and report output filename ("CodeNarcReport.html"). You can restrict which folders are included or add extra ones. See the "Configuring The CodeNarc RuleSet File(s)" section below for a list of the default rulesets, and information about how to use a custom ruleset.

Configuration Using "BuildConfig.groovy"

You can configure CodeNarc using several codenarc.XXX properties within "grails-app/conf/BuildConfig.groovy". (Note: Until version 0.14 of this plugin, this configuration was contained within "Config.groovy").

Configuring Reports

You configure one or more reports using the codenarc.reports property. Its value is a report DSL closure, e.g.

codenarc.reports = {    // Each report definition is of the form:
    //    REPORT-NAME(REPORT-TYPE) {
    //        PROPERTY-NAME = PROPERTY-VALUE
    //        PROPERTY-NAME = PROPERTY-VALUE
    //    }
    MyXmlReport('xml') {                    // The report name "MyXmlReport" is user-defined; Report type is 'xml'
        outputFile = 'CodeNarc-Report.xml'  // Set the 'outputFile' property of the (XML) Report
        title = 'Sample Report'             // Set the 'title' property of the (XML) Report
    }
    MyHtmlReport('html') {                  // Report type is 'html'
        outputFile = 'CodeNarc-Report.html'
        title = 'Sample Report'
    }
}

The valid report type values are 'html', 'sortable', 'xml', 'text' and 'ide', or the fully-qualified class name of a CodeNarc ReportWriter class

The following properties are deprecated, but are currently still supported. They are ignored if a codenarc.reports property is configured.

codenarc.reportName - The name of the analysis report file. (DEPRECATED)
codenarc.reportType - The report type. (DEPRECATED)
codenarc.reportTitle - The report title. (DEPRECATED)

Configuring The CodeNarc RuleSet File(s)

Use the codenarc.ruleSetFiles property to specify a comma-separated list of CodeNarc RuleSet files.

The default value is "rulesets/basic.xml,rulesets/exceptions.xml, rulesets/imports.xml,rulesets/grails.xml, rulesets/unused.xml". By default, these names are relative to the classpath. If you want to reference filesystem paths, prefix the ruleset path with "file:", e.g.

codenarc.ruleSetFiles="file:grails-app/conf/MyRuleSet.groovy"

You can also specify the value as a List of ruleset names (strings) rather than a single string, e.g.

codenarc.ruleSetFiles = ["rulesets/dry.xml", "rulesets/unnecessary.xml"]

Note that your custom ruleset cannot refer to a custom rule defined within the Grails application. This is due to a Grails classpath issue, discussed here.

Configuring Which Source Files Are Analyzed by CodeNarc

Use the processXXX properties to control which source directories are analyzed by CodeNarc.

codenarc.processSrcGroovy - Whether to analyze source in src/groovy (defaults to true)
codenarc.processControllers - Whether to analyze source in grails-app/controllers (defaults to true)
codenarc.processDomain - Whether to analyze source in grails-app/domain (defaults to true)
codenarc.processServices - Whether to analyze source in grails-app/services (defaults to true)
codenarc.processTaglib - Whether to analyze source in grails-app/taglib (defaults to true)
codenarc.processTestUnit - Whether to analyze source in test/unit (defaults to true)
codenarc.processTestIntegration - Whether to analyze source in test/integration (defaults to true)
codenarc.processViews - Whether to analyze GSP files under grails-app/views (defaults to false)
codenarc.extraIncludeDirs - Extra source directories to include; for example to include Quartz job files, specify

codenarc.extraIncludeDirs=['grails-app/jobs']

to add the pattern 'grails-app/jobs//*.groovy' to the analysis fileset

Configuring The Codenarc Properties

You configure one or more properties for rules in your ruleset using the codenarc.properties property. Its value is a properties DSL closure, e.g.

codenarc.properties = {
    // Each property definition is of the form:  RULE.PROPERTY-NAME = PROPERTY-VALUE
    GrailsPublicControllerMethod.enabled = false
    EmptyIfStatement.priority = 1
}

Alternatively, you can use an existing "codenarc.properties" file. Use the codenarc.propertiesFile property to set the path of the "codenarc.properties" properties file used to configure CodeNarc rules. e.g.

codenarc.propertiesFile = 'grails-app/conf/codenarc.properties'

Note that you can also set rule properties directly in your custom ruleset, if you use one.

Configuring Maximum Number of Violations

Use the codenarc.maxPriorityXViolations properties to set the maximum number of priority X violations allowed without causing a failure.

codenarc.maxPriority1Violations - The maximum number of Priority 1 violations allowed
codenarc.maxPriority2Violations - The maximum number of Priority 2 violations allowed
codenarc.maxPriority3Violations - The maximum number of Priority 3 violations allowed

Configuring Whether a Failure Prints a Failure Message or Throws a BuildException

The codenarc.systemExitOnBuildException controls what happens when the maximum number of violations are exceeded. If this property is true , print a FAILURE message to the console and call System.exit(1) when the build fails (due to exceeding the configured maximum number of violations. If the propery is false , a BuildException is thrown when the maximum number of violations are exceeded.

See http://codenarc.sourceforge.net/index.html for more information on CodeNarc configuration options.

Author

Chris Mair [email protected]

Please report any issues to the Grails User mailing list and/or write up an issue in GitHub at https://github.com/chrismair/GrailsCodeNarcPlugin/issues.

License

Licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0.

History

See Grails CodeNarc Plugin CHANGELOG

Plugins You can find out about all the publicly available Grails plugins.