CodeNarc plugin

  • Tags : code, quality, metrics
  • Latest : 0.18.1
  • Last Updated: 21 February 2013
  • Grails version : 1.3 > *
15 votes

9% of Grails users

Dependency : 
compile ":codenarc:0.18.1"

Documentation Source Issues

Summary

Runs CodeNarc static analysis rules for Groovy source.

Installation

grails install-plugin codenarc

Description

CodeNarc Plugin

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

NOTES:

  • 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.

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
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', '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"

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

  • Feb 21, 2013
    • Release version 0.18.1
      • Upgrade to CodeNarc 0.18.1
  • Dec 19, 2012
    • Release version 0.18
      • Upgrade to CodeNarc 0.18.
      • GPCODENARC-33: Upgraded to Grails 2.2-RC: 'ReportsDslDelegate' has an incorrect modifier private.
      • GPCODENARC-34: grails codenarc fails in case no "target" directory exists
      • Migrated to new Grails Plugin Repository
      • Moved source to GitHub: https://github.com/chrismair/GrailsCodeNarcPlugin.git
  • Apr 1, 2012
    • Release version 0.17
      • GPCODENARC-31: Upgrade to CodeNarc 0.17.
      • GPCODENARC-23. Allow ruleSetFiles to be a collection/list; e.g. codenarc.ruleSetFiles = "rulesets/dry.xml", "rulesets/unnecessary.xml" (+)
      • GPCODENARC-24: Create default report output file in "target" folder ("target/CodeNarcReport.html"); only used if no reports are explicitly defined.
      • GPCODENARC-30. Support codenarc.properties = { GrailsPublicControllerMethod.enabled = false } in "BuildConfig.groovy"
  • 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
"CodeNarc.groovy" to not crash id the "Config.groovy" file is missing.
      • 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:
javax.xml.XMLConstants gant.TargetExecutionException: 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
property to handle optional path (e.g. “abc/def/MyClass.groovy”).
  • 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
than (the default of) being relative to the classpath.
  • 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