Grails 3.x

Grails 2.x

build ":codenarc:1.3"

Grails 1.x

grails install-plugin codenarc

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

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

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: This plugin sets the codenarc.useCurrentThreadContextClassLoader system property to "true". That enables Grails CodeNarc plugin to refer to custom rule scripts in a Grails project, but not a rule class, though the script can refer to other classes in the Grails project. 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']

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.org/ 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