Step 1 (PR-G): Add grails-code-analysis convention plugin + violation aggregation

.agents/skills/violation-fixer/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: violation-fixer
+description: Guide for running, interpreting, and fixing code style and analysis violations in grails-core using GrailsCodeStylePlugin, GrailsCodeAnalysisPlugin, and GrailsViolationAggregationPlugin — covering CodeNarc, Checkstyle, PMD, SpotBugs, and JaCoCo
+license: Apache-2.0
+---
+<!--
+SPDX-License-Identifier: Apache-2.0
+
+Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements; and to You under the Apache License, Version 2.0. 
+-->
+
+## What I Do
+
+- Explain how `GrailsCodeStylePlugin`, `GrailsCodeAnalysisPlugin`, and `GrailsViolationAggregationPlugin` enforce 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 aggregateViolations` and interpreting the resulting `*_VIOLATIONS.md` files.
+- 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/codestyle/` |
+| `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/codeanalysis/` |
+| `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
+
+```bash
+# 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.codeanalysis.enabled.pmd=true
+
+# Full multi-module check + report
+./gradlew aggregateViolations
+
+# Include test sources in style checks
+./gradlew aggregateViolations -Pgrails.codestyle.enabled.tests=true
+
+# Include test sources in analysis
+./gradlew aggregateViolations -Pgrails.codeanalysis.enabled.tests=true
+
+# Ignore failures (collect reports without failing the build)
+./gradlew aggregateViolations -Pgrails.codestyle.ignoreFailures=true -Pgrails.codeanalysis.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/codestyle/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/codestyle/checkstyle/checkstyle.xml`.
+
+Common violations:
+
+| Rule | Fix |
+|------|-----|
+| `ImportOrder` | Re-order imports: `java|javax`, then `groovy`, then `jakarta`, then blank, then `io.spring|org.springframework`, then `grails|org.apache.grails|org.grails`, then static imports |
+| `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.codeanalysis.enabled.pmd=true`
+
+Rule file: `build/codeanalysis/pmd/pmd.xml`.
+
+### SpotBugs (Java bytecode — opt-in)
+
+Enable: `-Pgrails.codeanalysis.enabled.spotbugs=true`
+
+Runs at `Effort.MAX` / `Confidence.HIGH`. Only high-confidence bugs are reported.
+
+### Spotless (Java auto-formatting — opt-in)
+
+Enable: `-Pgrails.codestyle.enabled.spotless=true`
+
+Uses Palantir Java Format. Can auto-fix by running:
+```bash
+./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.codestyle.enabled.checkstyle` | `true` | Enable Checkstyle |
+| `grails.codestyle.enabled.codenarc` | `true` | Enable CodeNarc |
+| `grails.codestyle.enabled.spotless` | `false` | Enable Spotless |
+| `grails.codestyle.enabled.tests` | `false` | Also check test source sets |
+| `grails.codestyle.ignoreFailures` | `false` | Collect reports without failing build |
+| `grails.codestyle.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.codeanalysis.enabled.pmd` | `false` | Enable PMD |
+| `grails.codeanalysis.enabled.spotbugs` | `false` | Enable SpotBugs |
+| `grails.codeanalysis.enabled.tests` | `false` | Also analyse test source sets |
+| `grails.codeanalysis.ignoreFailures` | `false` | Collect reports without failing build |
+| `grails.codeanalysis.dir.pmd` | (auto) | Custom path to PMD config dir |
+| `skipCodeStyle` | unset | If present, all analysis tasks are also skipped |
+
+---
+
+## Fixing Violations Workflow
+
+1. Run `./gradlew aggregateViolations -Pgrails.codestyle.ignoreFailures=true -Pgrails.codeanalysis.ignoreFailures=true`
+2. Open `build/reports/violations/CODENARC_VIOLATIONS.md` and `build/reports/violations/CHECKSTYLE_VIOLATIONS.md` to see all issues by module
+3. For CodeNarc, run `./gradlew codenarcFix` to auto-fix what it can
+4. Fix remaining violations manually using the table above
+5. Re-run `./gradlew aggregateViolations` and confirm files contain `No violations found! 🎉`
+6. 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/codestyle/        ← XML inputs for style aggregation
+├── checkstyle/
+│   ├── grails-core-checkstyleMain.xml
+│   ├── grails-web-mvc-checkstyleMain.xml
+│   └── ...
+└── codenarc/
+    ├── grails-core-codenarcMain.xml
+    └── ...
+
+build/reports/codeanalysis/     ← 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`).

.github/workflows/codeanalysis.yml

@@ -0,0 +1,95 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: "Code Analysis"
+on:
+  push:
+    branches:
+      - '[0-9]+.[0-9]+.x'
+      - '8.0.x-hibernate7.*'
+  pull_request:
+  workflow_dispatch:
+# queue jobs and only allow 1 run per branch due to the likelihood of hitting GitHub resource limits
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  check_core_projects:
+    name: "Core Projects"
+    runs-on: ubuntu-24.04
+    steps:
+      - name: "🌐 Output Agent IP" # in the event RAO blocks this agent, this can be used to debug it
+        run: curl -s https://api.ipify.org
+      - name: "📥 Checkout repository"
+        uses: actions/checkout@v6
+      - name: "☕️ Setup JDK"
+        uses: actions/setup-java@v4
+        with:
+          distribution: liberica
+          java-version: 21
+      - name: "🐘 Setup Gradle"
+        uses: gradle/actions/setup-gradle@4d9f0ba0025fe599b4ebab900eb7f3a1d93ef4c2 # v5.0.0
+        with:
+          develocity-access-key: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
+      - name: "🔎 Check Core Projects"
+        run: ./gradlew aggregateAnalysisViolations --continue -Pgrails.codeanalysis.enabled.pmd=true -Pgrails.codeanalysis.enabled.spotbugs=true
+      - name: "📤 Upload Reports"
+        if: always()
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: core-reports
+          path: build/reports/violations/
+      - name: "📋 Publish Code Analysis Report in Job Summary"
+        if: always()
+        run: |
+          echo "## 🔎 Code Analysis Report - Core Projects" >> $GITHUB_STEP_SUMMARY
+          for report in PMD_VIOLATIONS.md SPOTBUGS_VIOLATIONS.md; do
+            file="build/reports/violations/$report"
+            [ -f "$file" ] && cat "$file" >> $GITHUB_STEP_SUMMARY || true
+          done
+  check_gradle_plugin_projects:
+    name: "Gradle Plugin Projects"
+    runs-on: ubuntu-24.04
+    steps:
+      - name: "🌐 Output Agent IP" # in the event RAO blocks this agent, this can be used to debug it
+        run: curl -s https://api.ipify.org
+      - name: "📥 Checkout repository"
+        uses: actions/checkout@v6
+      - name: "☕️ Setup JDK"
+        uses: actions/setup-java@v4
+        with:
+          distribution: liberica
+          java-version: 21
+      - name: "🐘 Setup Gradle"
+        uses: gradle/actions/setup-gradle@4d9f0ba0025fe599b4ebab900eb7f3a1d93ef4c2 # v5.0.0
+        with:
+          develocity-access-key: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
+      - name: "🔎 Check Gradle Plugin Projects"
+        working-directory: grails-gradle
+        run: ./gradlew aggregateAnalysisViolations --continue -Pgrails.codeanalysis.enabled.pmd=true -Pgrails.codeanalysis.enabled.spotbugs=true
+      - name: "📤 Upload Reports"
+        if: always()
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: gradle-plugin-reports
+          path: grails-gradle/build/reports/violations/
+      - name: "📋 Publish Code Analysis Report in Job Summary"
+        if: always()
+        run: |
+          echo "## 🔎 Code Analysis Report - Gradle Plugin Projects" >> $GITHUB_STEP_SUMMARY
+          for report in PMD_VIOLATIONS.md SPOTBUGS_VIOLATIONS.md; do
+            file="grails-gradle/build/reports/violations/$report"
+            [ -f "$file" ] && cat "$file" >> $GITHUB_STEP_SUMMARY || true
+          done