apache What I Do
- Explain how
GrailsCodeStylePlugin,GrailsCodeAnalysisPlugin, andGrailsViolationAggregationPluginenforce code quality across all 60+ modules. - Guide you through running style and analysis checks, interpreting the per-tool Markdown violation reports, and fixing each class of violation.
- Describe which tools are always-on vs. opt-in, how to configure them via Gradle properties, and which violations can be auto-fixed.
When to Use Me
Activate this skill when:
- Running
./gradlew aggregateViolationsand interpreting the resulting*_VIOLATIONS.mdfiles. - Fixing CodeNarc, Checkstyle, PMD, SpotBugs, or Spotless violations reported in those files.
- Configuring code style or analysis tools across the repo (enabling/disabling tools or adjusting rule files).
- Preparing a commit — the plugin output must be clean before merging.
Plugin Overview
| Plugin | Applied to | Responsibility |
|---|---|---|
org.apache.grails.gradle.grails-code-style |
Every subproject | Applies Checkstyle and CodeNarc; registers per-project codeStyle task; redirects XML reports to root build/reports/code-style/ |
org.apache.grails.gradle.grails-code-analysis |
Every subproject | Applies PMD and SpotBugs (both opt-in); registers per-project codeAnalysis task; redirects XML reports to root build/reports/code-analysis/ |
org.apache.grails.gradle.grails-jacoco |
Every subproject | Applies JaCoCo; wires jacocoTestReport to run after each test task |
org.apache.grails.gradle.grails-violation-aggregation |
Root project only | Registers aggregateViolations and aggregateJacocoCoverage tasks; writes Markdown summaries to build/reports/violations/ |
Key Tasks
| Task | Scope | Description |
|---|---|---|
./gradlew codeStyle |
per-project | Runs Checkstyle and CodeNarc for that project |
./gradlew codeAnalysis |
per-project | Runs PMD and/or SpotBugs for that project (when enabled) |
./gradlew aggregateViolations |
root | Runs all checks across every module, then writes *_VIOLATIONS.md to build/reports/violations/ |
./gradlew aggregateJacocoCoverage |
root | Runs JaCoCo reports across every module, then writes JACOCO_COVERAGE.md to build/reports/violations/ |
./gradlew codenarcFix |
per-project | Auto-fixes a subset of CodeNarc violations |
Quick commands
# Check a single module (style only)
./gradlew :grails-core:codeStyle
# Check a single module (analysis — must be enabled via properties)
./gradlew :grails-core:codeAnalysis -Pgrails.code-analysis.enabled.pmd=true
# Full multi-module check + report
./gradlew aggregateViolations
# Include test sources in style checks
./gradlew aggregateViolations -Pgrails.code-style.enabled.tests=true
# Include test sources in analysis
./gradlew aggregateViolations -Pgrails.code-analysis.enabled.tests=true
# Ignore failures (collect reports without failing the build)
./gradlew aggregateViolations -Pgrails.code-style.ignoreFailures=true -Pgrails.code-analysis.ignoreFailures=true
# Auto-fix some CodeNarc violations before running checks
./gradlew codenarcFix codeStyle
# JaCoCo coverage report
./gradlew aggregateJacocoCoverage
Output Files
After running aggregateViolations, these files appear under build/reports/violations/ in the root project build directory:
| File | Tool | Always generated |
|---|---|---|
build/reports/violations/CODENARC_VIOLATIONS.md |
CodeNarc | Yes |
build/reports/violations/CHECKSTYLE_VIOLATIONS.md |
Checkstyle | Yes |
build/reports/violations/PMD_VIOLATIONS.md |
PMD | Yes — contains No violations found! when PMD is disabled |
build/reports/violations/SPOTBUGS_VIOLATIONS.md |
SpotBugs | Yes — contains No violations found! when SpotBugs is disabled |
After running aggregateJacocoCoverage:
| File | Tool | Generated |
|---|---|---|
build/reports/violations/JACOCO_COVERAGE.md |
JaCoCo | Only when at least one subproject has a JaCoCo CSV report |
All reports are inside build/ and are excluded from version control via .gitignore. A clean run produces No violations found! 🎉 in each style file. The build must be clean before committing.
Each file is a Markdown table grouped by module, with columns: Class, Tool, Violation, Line, Message.
Tool Details
CodeNarc (Groovy — always enabled)
Rule file: build/code-style/codenarc/codenarc.groovy (generated by the plugin during setup; not intended to be edited directly).
Most common violations and how to fix them:
| Rule | Fix |
|---|---|
UnnecessaryGString |
Replace "plain string" with 'plain string' |
UnnecessarySemicolon |
Remove trailing ; |
SpaceBeforeOpeningBrace |
Add space before { → method() { |
SpaceAroundMapEntryColon |
[key: value] not [key:value] |
ConsecutiveBlankLines |
Collapse 3+ blank lines to 2 |
ClassStartsWithBlankLine |
Remove blank line right after class Foo { |
NoWildcardImports |
Expand import org.foo.* to explicit imports |
UnusedImport |
Remove imports not referenced in the file |
MethodName |
Method names must be camelCase (not snake_case) |
VariableName |
Variable names must be camelCase |
LineLength |
Keep lines ≤ 200 chars (default) |
Auto-fixable via codenarcFix: ClassStartsWithBlankLine, SpaceAroundMapEntryColon, UnnecessaryGString, UnnecessarySemicolon, SpaceBeforeOpeningBrace, ConsecutiveBlankLines.
Checkstyle (Java — always enabled)
Rule file: build/code-style/checkstyle/checkstyle.xml.
Common violations:
| Rule | Fix |
|---|---|
ImportOrder |
Re-order imports: `java |
AvoidStarImport |
Use explicit class imports |
UnusedImports |
Remove unused imports |
WhitespaceAround |
Add spaces around operators and keywords |
NeedBraces |
Add {} to single-statement if/for/while |
FileTabCharacter |
Replace tabs with 4 spaces |
NewlineAtEndOfFile |
Ensure file ends with \n |
PMD (Java/Groovy — opt-in)
Enable: -Pgrails.code-analysis.enabled.pmd=true
Rule file: build/code-analysis/pmd/pmd.xml.
SpotBugs (Java bytecode — opt-in)
Enable: -Pgrails.code-analysis.enabled.spotbugs=true
Runs at Effort.MAX / Confidence.HIGH. Only high-confidence bugs are reported.
Spotless (Java auto-formatting — opt-in)
Enable: -Pgrails.code-style.enabled.spotless=true
Uses Palantir Java Format. Can auto-fix by running:
./gradlew spotlessApply
Configuration Properties
All properties can be set in gradle.properties or passed as -P flags:
grails-code-style plugin (Checkstyle + CodeNarc)
| Property | Default | Description |
|---|---|---|
grails.code-style.enabled.checkstyle |
true |
Enable Checkstyle |
grails.code-style.enabled.codenarc |
true |
Enable CodeNarc |
grails.code-style.enabled.spotless |
false |
Enable Spotless |
grails.code-style.enabled.tests |
false |
Also check test source sets |
grails.code-style.ignoreFailures |
false |
Collect reports without failing build |
grails.code-style.codenarc.fix |
false |
Run codenarcFix before CodeNarc tasks |
grails.codestyle.dir.checkstyle |
(auto) | Custom path to Checkstyle config dir |
grails.codestyle.dir.codenarc |
(auto) | Custom path to CodeNarc config dir |
skipCodeStyle |
unset | If present, all style tasks are skipped |
grails-code-analysis plugin (PMD + SpotBugs)
| Property | Default | Description |
|---|---|---|
grails.code-analysis.enabled.pmd |
false |
Enable PMD |
grails.code-analysis.enabled.spotbugs |
false |
Enable SpotBugs |
grails.code-analysis.enabled.tests |
false |
Also analyse test source sets |
grails.code-analysis.ignoreFailures |
false |
Collect reports without failing build |
grails.code-analysis.dir.pmd |
(auto) | Custom path to PMD config dir |
skipCodeStyle |
unset | If present, all analysis tasks are also skipped |
Fixing Violations Workflow
- Run
./gradlew aggregateViolations -Pgrails.code-style.ignoreFailures=true -Pgrails.code-analysis.ignoreFailures=true - Open
build/reports/violations/CODENARC_VIOLATIONS.mdandbuild/reports/violations/CHECKSTYLE_VIOLATIONS.mdto see all issues by module - For CodeNarc, run
./gradlew codenarcFixto auto-fix what it can - Fix remaining violations manually using the table above
- Re-run
./gradlew aggregateViolationsand confirm files containNo violations found! 🎉 - The reports are inside
build/and do not need to be deleted before committing
Reports Directory Structure
All XML reports are consolidated at:
build/reports/code-style/ ← XML inputs for style aggregation
├── checkstyle/
│ ├── grails-core-checkstyleMain.xml
│ ├── grails-web-mvc-checkstyleMain.xml
│ └── ...
└── codenarc/
├── grails-core-codenarcMain.xml
└── ...
build/reports/code-analysis/ ← XML inputs for analysis aggregation (if enabled)
├── pmd/
└── spotbugs/
build/reports/violations/ ← Markdown summaries written by aggregateViolations
├── CODENARC_VIOLATIONS.md
├── CHECKSTYLE_VIOLATIONS.md
├── PMD_VIOLATIONS.md
├── SPOTBUGS_VIOLATIONS.md
└── JACOCO_COVERAGE.md ← written by aggregateJacocoCoverage
The module name is derived from the filename: everything before the last - (e.g. grails-core-checkstyleMain.xml → module grails-core).