Document CodeNarc configuration for Grails projects

[jamesfredley]

Summary

Adds a new "Code Quality with CodeNarc" section to the Testing chapter of the Grails documentation, covering Gradle plugin setup, the GORM AST transformer compatibility issue with ruleset imports, and the recommended individual-rule configuration approach.

Problem

When Grails developers integrate CodeNarc for static analysis, the natural approach is to import pre-built rulesets:

ruleset {
    ruleset('rulesets/basic.xml')
    ruleset('rulesets/formatting.xml')
}

This fails in Grails projects because some CodeNarc rules ("enhanced" rules) perform semantic analysis at Groovy compiler phase 4. These rules attempt to resolve GORM AST-transformed classes (OrderedGormTransformation, ServiceTransformation) that are not available on CodeNarc's classpath. The result is ClassNotFoundException or NoClassDefFoundError during analysis.

Adding compilationClasspath to the CodeNarc Gradle task helps with basic class resolution but does not make GORM's transformation processors available, so enhanced rules still fail.

There is currently no mention of CodeNarc anywhere in the Grails documentation.

Solution

The new codeQuality.adoc section documents:

1. Gradle plugin setup - applying the CodeNarc plugin with the correct -groovy-4.0 artifact variant and strict violation thresholds
2. GORM AST compatibility - explains why ruleset() imports fail in Grails projects
3. Recommended configuration - the exact ruleset from grails-core's own build, listing individual rules explicitly to avoid enhanced rules that require GORM's AST infrastructure
4. Separate test ruleset - guidance on configuring a more lenient ruleset for Spock specs
5. Reference - links to grails-core's own CodeNarc config as the canonical starting point

The documented ruleset matches grails-core's canonical codenarc.groovy exactly, and the Gradle configuration follows the pattern established in grails-server-timing's feedback branch (strict maxPriorityNViolations = 0 thresholds, no ignoreFailures).

Files Changed

• grails-doc/src/en/guide/toc.yml - Added codeQuality entry under testing: section
• grails-doc/src/en/guide/testing/codeQuality.adoc - New documentation file

Verification

• The documented ruleset is identical to build-logic/plugins/src/main/resources/META-INF/org.apache.grails.buildsrc.codestyle/codenarc/codenarc.groovy
• The CodeNarc version (3.6.0-groovy-4.0) matches gradle.properties
• The Gradle configuration pattern (strict violation thresholds, no ignoreFailures) matches grails-server-timing feedback branch

[Copilot]

Pull request overview

Adds documentation to the Grails user guide describing how to configure and use CodeNarc in Grails projects, including the known GORM AST-related incompatibilities with importing built-in CodeNarc rulesets.

Changes:

• Added a new “Code Quality with CodeNarc” entry to the Testing chapter TOC.
• Added a new codeQuality.adoc guide covering Gradle setup, the ruleset-import pitfall, and recommended per-rule configuration.
• Documented using a separate, more lenient CodeNarc configuration for test sources.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
grails-doc/src/en/guide/toc.yml	Adds codeQuality page under the Testing chapter navigation.
grails-doc/src/en/guide/testing/codeQuality.adoc	New documentation page describing CodeNarc setup and Grails/GORM-specific caveats.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jdaugherty]

I don't dispute this is good to add, but I'm currently reworking the "example" project for this and this overlaps strongly with that work.

The examples you show do not follow the feedback that @matrei has given on the sample project. Can we update these?

[jamesfredley]

Updated to match the examples exactly.

Commit with changes pushed