CodeNarc Plugin

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

NOTE: 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.

NOTE: 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.

Installation

To integrate the plugin into your application just run the 'install-plugin' Grails script, e.g.

grails install-plugin codenarc

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', 'xml' and 'text', 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"

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']

Configuring The Location of the "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'

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 chrismair@users.sourceforge.net

Please report any issues to the Grails User mailing list and/or write up an issue in JIRA at http://jira.grails.org/browse/GPCODENARC.

License

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

History

• Nov 14, 2011
• Release version 0.16.1
• Upgrade to CodeNarc 0.16.1
• Add extra plugin metadata to descriptor
• Aug 5, 2011
• Release version 0.15
• Upgrade to CodeNarc 0.15
• Fix GPCODENARC-20. Create report outputFile folders if missing. See CodeNarc issue #3380494.
• Fix GPCODENARC-15. Can’t run CodeNarc with Grails 2.0. Fixed by CodeNarc 0.15.
• Fix GPCODENARC-16. NoClassDefFoundError: org/codehaus/groovy/transform/powerassert/ValueRecorder – running with Groovy 1.8. Fixed by CodeNarc 0.15.
• Jul 2, 2011
• Release version 0.14
• Feature: GPCODENARC-19. Upgrade to CodeNarc 0.14
• Feature: GPCODENARC-18. Move configuration to “BuildConfig.groovy”. Write out warning message if CodeNarc config still exists in “Config.groovy”.
• Fix http://jira.grails.org/browse/GPCODENARC-13. Including AbcComplexity and CyclomaticComplexity rules in ruleset makes no rules work. Include GMetrics jar as a dependency.
• Fix GPCODENARC-14. Exclude CodeNarc Plugin from war builds by default.
• Apr 3, 2011
• Release version 0.12
• Fix #11: Allow CodeNarc rules to be applied to GSP files
• Feature #7: Add support for multiple reports
• Fix #9: Provide error message on failure instead of throwing BuildException
• Mar 11, 2011
• Release version 0.11
• Fixed dependencies so that CodeNarc jar is no longer bundled in the WAR Grails creates.
• Mar 6, 2011
• Release version 0.10
• Upgrade to CodeNarc v0.13
• Jan 20, 2011
• Release version 0.9
• Upgrade to CodeNarc v0.12
• Upgrade to Grails 1.3.4
• Dec 25, 2010
• Release version 0.8.1
• Fix GRAILSPLUGINS-2709. “Change target named default … to something else”.
• Nov 14, 2010
• Release version 0.8
• Upgrade to CodeNarc v0.11. NOTE: CodeNarc v0.11 requires Groovy 1.7, so it cannot be used by projects on older versions of Grails (pre-Grails 1.3)
• Oct 3, 2010
• Release version 0.7
• Upgrade to CodeNarc v0.10.
• Add support in "Config.groovy" for using a custom “codenarc.properties”.
• Within "Config.groovy": Set an optional property: e.g. codenarc.propertiesFile = 'grails-app/conf/codenarc.properties'
• (This automatically prepends a "file:" prefix so that it is interpreted as a filesystem path rather than relative to the classpath).
• May 27, 2010
• Release version 0.6.1
• Fix bug GRAILSPLUGINS-2193. “CodeNarc plugin doesn’t run (on Grails 1.3.1)”. Explicitly set default target within “Codenarc.groovy” script.
• May 21, 2010
• Release version 0.6
• Fix bug #1941: "Getting error trying grails codenarc using 0.4 in grails 1.2.1". http://jira.codehaus.org/browse/GRAILSPLUGINS-1941. Modify

• Upgrade to CodeNarc 0.9:
• CodeNarcRunner fixed to also println() summary in addition to LOG.info(). (Fixed in CodeNarc v0.9)
• Fix "Error executing script Codenarc: groovy.lang.MissingPropertyException: No such property: W3C_XML_SCHEMA_NS_URI for class:

(Fixed in CodeNarc v0.9)

• February 3, 2010
• Release version 0.5
• Upgrade to CodeNarc 0.8.1 (bug fixes).
• January 19, 2010
• Release version 0.4
• Upgrade to CodeNarc 0.8. This includes XML and Text report formats (beta), a new NestedBlockDepthRule, enhancement of the applyToFileNames rule

• August 26, 2009
• Released version 0.3
• Upgrade to CodeNarc 0.7. This includes support for optionally prefixing ruleset file paths with "file:" to indicate a relative or absolute path in the filesystem rather

• July 18, 2009
• Released version 0.2
• Add “Unused” ruleset to default rulesets.
• Upgrade to CodeNarc 0.6.
• Include “test” folders in analysis; add codenarc.processTestUnit and codenarc.processTestIntegration properties in Config.groovy.
• Rename default report file to “CodeNarcReport.html”.
• Update author and authorEmail fields in CodenarcGrailsPlugin. (Original=Burt Beckwith).
• Create automated test for CodeNarc plugin.
• May 25, 2009
• released initial version 0.1