feat(ci): add SpotBugs and PMD static analysis (#369)

* feat(static-analysis): add SpotBugs and PMD code quality tools

- Add SpotBugs 4.8.6.6 with FindSecBugs plugin to parent pom.xml
- Add PMD 7.9.0 with custom ruleset to parent pom.xml
- Create spotbugs/exclude-filter.xml for QQQ-specific exclusions
- Create pmd/ruleset.xml tuned for QQQ conventions
- Update CircleCI config to use qqq-orb static_analysis workflow
- Report-only by default; use -Dspotbugs.failOnError=true to fail

* ci: run static analysis in parallel with tests

* feat(ci): add SpotBugs and PMD static analysis to CI pipeline

Run static_analysis job in parallel with tests on feature branches.

Author: KofTwentyTwo

.circleci/config.yml

@@ -3,7 +3,7 @@
 version: 2.1
 
 orbs:
-  qqq-orb: kingsrook/qqq-orb@0.5.0
+  qqq-orb: kingsrook/qqq-orb@0.6.0
 
 workflows:
 
@@ -16,6 +16,14 @@ workflows:
               ignore: /(develop|main|release/.*|hotfix/.*|integration.*)/
             tags:
               only: []
+      # Static analysis runs in parallel with tests
+      - qqq-orb/static_analysis:
+          context: [qqq-maven-registry-credentials]
+          filters:
+            branches:
+              ignore: /(develop|main|release/.*|hotfix/.*|integration.*)/
+            tags:
+              only: []
 
   publish_snapshot:
     jobs:
@@ -26,6 +34,12 @@ workflows:
             branches:
               only:
                 - develop
+      - qqq-orb/static_analysis:
+          context: [qqq-maven-registry-credentials]
+          filters:
+            branches:
+              only:
+                - develop
 
   publish_feature:
     jobs:

docs/PLAN-spotbugs-pmd.md

@@ -0,0 +1,57 @@
+# PLAN: SpotBugs + PMD Code Quality Integration
+
+## Goal
+
+Add SpotBugs and PMD static analysis to the QQQ build for local execution and optional CI/CD.
+
+## Approach
+
+1. **Maven Integration** - Add plugins to parent pom.xml with sensible defaults
+2. **Non-blocking by default** - Warnings reported but don't fail builds initially
+3. **Optional CI workflow** - Manual trigger GitHub Action for on-demand analysis
+
+## Configuration Strategy
+
+| Tool | Phase | Default | Override Property |
+|------|-------|---------|-------------------|
+| SpotBugs | verify | report only | `-Dspotbugs.failOnError=true` |
+| PMD | verify | report only | `-Dpmd.failOnViolation=true` |
+
+## Files to Create/Modify
+
+- `pom.xml` - Add plugin configurations
+- `spotbugs/exclude-filter.xml` - Exclusions for known false positives
+- `pmd/ruleset.xml` - Custom ruleset tuned for QQQ
+- `.github/workflows/static-analysis.yml` - Optional CI workflow
+
+## Local Commands
+
+```bash
+# Run SpotBugs only
+mvn spotbugs:check
+
+# Run PMD only
+mvn pmd:check
+
+# Run both during verify
+mvn verify
+
+# Fail on issues (CI mode)
+mvn verify -Dspotbugs.failOnError=true -Dpmd.failOnViolation=true
+```
+
+## Plugin Versions
+
+- SpotBugs Maven Plugin: 4.8.6.6
+- PMD Maven Plugin: 3.26.0
+- PMD: 7.9.0
+
+## Exclusion Strategy
+
+SpotBugs exclusions for QQQ patterns:
+- `EI_EXPOSE_REP` / `EI_EXPOSE_REP2` - Fluent builders intentionally expose mutable state
+- `NP_NULL_ON_SOME_PATH` - QContext patterns with known null handling
+
+PMD suppressions:
+- `AvoidFieldNameMatchingMethodName` - QQQ getter/setter pattern
+- `TooManyMethods` - MetaData classes are large by design

docs/SESSION.md

@@ -1,59 +1,79 @@
 # Session State
 
-**Last Updated:** 2026-01-09
-**Branch:** `develop`
-**Last Task:** PR Merge and Daily Build Log
+**Last Updated:** 2026-01-14
+**Branch:** `feature/implement-spotbugs`
+**Last Task:** SpotBugs + PMD Static Analysis Implementation
 
 ## Current Context
 
-Completed merging 5 PRs into develop and created a Daily Build Log discussion on GitHub to document the changes.
+Implemented SpotBugs and PMD static analysis for QQQ with both local Maven execution and CircleCI orb support.
 
 ## Completed This Session
 
-1. **PR Merge Plan** - Created `docs/PLAN-pr-merge-order.md` with optimal merge strategy
+1. **Maven Plugin Configuration** - Added SpotBugs and PMD plugins to parent pom.xml
+   - SpotBugs 4.8.6.6 with FindSecBugs plugin
+   - PMD 7.9.0 with custom ruleset
+   - Report-only by default (`-Dspotbugs.failOnError=true` / `-Dpmd.failOnViolation=true` to fail)
 
-2. **Merged 5 PRs to develop** (in order):
-   - PR #321 - fix(personalization): child-table meta-data (`b2837708`)
-   - PR #320 - fix(bulkEditWithFile): avoid huge query results (`dea9c2a4`)
-   - PR #335 - fix(rdbms): PostgreSQL timestamp/identifier fixes (`886f86f1`)
-   - PR #337 - feat(auth): OAuth2 customizer support (`53d6a5bc`)
-   - PR #280 - feat: virtual fields and alternative sections (`a9eb8d28`)
+2. **Configuration Files Created**
+   - `spotbugs/exclude-filter.xml` - Exclusions for QQQ patterns (fluent builders, singletons)
+   - `pmd/ruleset.xml` - Custom ruleset tuned for QQQ conventions
 
-3. **Post-Merge Validation**
-   - qqq-backend-core: 147 tests passed
-   - qqq-backend-module-postgres: 42 tests passed
-   - Checkstyle: 0 violations
+3. **QQQ-Orb Enhancements** (in `/Users/james.maes/Git.Local/QRun-IO/qqq-orb/`)
+   - `src/commands/mvn_spotbugs.yml` - SpotBugs command
+   - `src/commands/mvn_pmd.yml` - PMD command
+   - `src/commands/collect_static_analysis_reports.yml` - Report collector
+   - `src/jobs/static_analysis.yml` - Combined analysis job
+   - `src/scripts/mvn_spotbugs.sh`, `mvn_pmd.sh`, `collect_static_analysis_reports.sh`
 
-4. **Daily Build Log** - Created GitHub Discussion #340
-   - Category: Daily Build Log
-   - Title: "Five PRs Hit Develop: Virtual Fields, OAuth2 Customizers, and Three Production Fixes"
-   - URL: https://github.com/orgs/QRun-IO/discussions/340
+4. **Local Testing** - Verified both tools work
+   - SpotBugs found ~100 issues (many false positives for singletons/fluent APIs)
+   - PMD found ~2800 violations (many low-priority style suggestions)
 
-## Open Items
+## Files Modified/Created
 
-- **Issue #336** - Feature: Pluggable QSessionStoreInterface QBit (future work)
-- **License Migration** - Paused, see `docs/PLAN-license-migration.md`
+### QQQ Repo
+- `pom.xml` - Added SpotBugs and PMD plugin configurations
+- `spotbugs/exclude-filter.xml` - NEW
+- `pmd/ruleset.xml` - NEW
+- `.circleci/config.yml` - Added pipeline parameter and commented example workflow
+- `docs/PLAN-spotbugs-pmd.md` - NEW
+
+### QQQ-Orb Repo
+- `src/commands/mvn_spotbugs.yml` - NEW
+- `src/commands/mvn_pmd.yml` - NEW
+- `src/commands/collect_static_analysis_reports.yml` - NEW
+- `src/jobs/static_analysis.yml` - NEW
+- `src/scripts/mvn_spotbugs.sh` - NEW
+- `src/scripts/mvn_pmd.sh` - NEW
+- `src/scripts/collect_static_analysis_reports.sh` - NEW
+
+## Local Commands
+
+```bash
+# Run SpotBugs (report only)
+mvn spotbugs:check -DskipTests
+
+# Run PMD (report only)
+mvn pmd:check -DskipTests
+
+# Run both with failure on issues
+mvn verify -Dspotbugs.failOnError=true -Dpmd.failOnViolation=true
+
+# Run on single module
+mvn spotbugs:check pmd:check -pl qqq-backend-core -DskipTests
+```
+
+## Next Steps
+
+1. **Publish qqq-orb@0.6.0** - Bump version and publish to CircleCI registry
+2. **Uncomment static_analysis workflow** - After orb is published
+3. **Tune exclusions** - Review findings and add exclusions for false positives
+4. **Consider making PMD stricter** - Exclude more low-priority rules
 
 ## To Continue
 
 Say **"continue from last session"** and Claude will:
 1. Read this file and `docs/TODO.md`
 2. Check for any pending work
 3. Resume from last checkpoint
-
-## Key Files Reference
-
-### New Classes (from merged PRs)
-- `qqq-backend-core/.../metadata/fields/QVirtualFieldMetaData.java`
-- `qqq-backend-core/.../tables/QFieldSectionAlternativeType.java`
-- `qqq-backend-core/.../widgets/blocks/icon/IconBlockData.java`
-
-### Modified Classes
-- `qqq-backend-core/.../OAuth2AuthenticationModule.java` (customizer support)
-- `qqq-backend-core/.../BulkInsertTransformStep.java` (three-tier fallback)
-- `qqq-backend-module-rdbms/.../QueryManager.java` (TIMESTAMPTZ parsing)
-- `qqq-backend-core/.../ChildRecordListData.java` (personalization fix)
-
-### Documentation
-- `docs/PLAN-pr-merge-order.md` - PR merge plan (completed)
-- `docs/PLAN-license-migration.md` - License migration plan (paused)

docs/TODO.md

@@ -1,72 +1,65 @@
 # TODO
 
-## Recently Completed (2026-01-09)
-
-### PR Merge Task
-- [x] Create merge plan (`docs/PLAN-pr-merge-order.md`)
-- [x] Merge PR #321 - child-table personalization fix
-- [x] Merge PR #320 - bulk edit query optimization
-- [x] Merge PR #335 - PostgreSQL timestamp/identifier fixes
-- [x] Merge PR #337 - OAuth2 customizer support
-- [x] Merge PR #280 - virtual fields and alternative sections
-- [x] Post-merge validation (189 tests)
-- [x] Create Daily Build Log (Discussion #340)
-
-### Issue #334 - OAuth2 Session Security Keys
-- [x] Add customizer support to OAuth2AuthenticationModule
-- [x] Add unit tests and integration tests
-- [x] Create PR #337 (MERGED)
-- [x] Create GitHub issue #336 for Phase 2 QBit
+## Completed (2026-01-14)
+
+### SpotBugs + PMD Implementation
+- [x] Create implementation plan (`docs/PLAN-spotbugs-pmd.md`)
+- [x] Add SpotBugs Maven plugin to parent pom.xml
+- [x] Create SpotBugs exclusion filter (`spotbugs/exclude-filter.xml`)
+- [x] Add PMD Maven plugin to parent pom.xml
+- [x] Create PMD ruleset (`pmd/ruleset.xml`)
+- [x] Test local Maven execution
+- [x] Add static analysis commands to qqq-orb
+- [x] Add static analysis job to qqq-orb
+- [x] Update CircleCI config with pipeline parameter
 
 ---
 
 ## Pending Work
 
-### Future: Issue #336 - QSessionStoreInterface QBit
-- [ ] Design pluggable session store interface
-- [ ] Implement default in-memory store
-- [ ] Add Redis/database store options
-- [ ] Documentation
+### Orb Release Required
+- [ ] Bump qqq-orb version to 0.6.0
+- [ ] Publish qqq-orb to CircleCI registry
+- [ ] Uncomment static_analysis workflow in qqq `.circleci/config.yml`
+
+### Future: Tune Static Analysis
+- [ ] Review SpotBugs findings and add targeted exclusions
+- [ ] Review PMD findings and tune ruleset
+- [ ] Consider enabling `failOnError` for specific high-priority rules
 
 ### Background: License Migration (Paused)
 See `docs/PLAN-license-migration.md` for details.
 
-- [x] Push LICENSE, NOTICE, README to all 25 repos
-- [x] Delete old LICENSE.txt files
-- [x] Update `checkstyle/license.txt` header
-- [ ] Update Java source file headers (~5,747 files)
-- [ ] Update pom.xml `<licenses>` sections (~20 files)
-- [ ] Update README.md AGPL references (~15 files)
-- [ ] Update package.json license field (qqq-frontend-core)
-- [ ] Run checkstyle to verify headers
-
 ---
 
-## Notes
+## Quick Reference
 
-### New Features Available (v0.36.0-SNAPSHOT)
+### Local Static Analysis Commands
+```bash
+# SpotBugs only
+mvn spotbugs:check -DskipTests
 
-**Virtual Fields:**
-```java
-new QTableMetaData()
-   .withVirtualField(new QVirtualFieldMetaData("computed")
-      .withType(QFieldType.STRING));
-```
+# PMD only
+mvn pmd:check -DskipTests
 
-**Alternative Sections:**
-```java
-new QFieldSection()
-   .withAlternative(QFieldSectionAlternativeType.MOBILE,
-      new QFieldSection().withFields(List.of("name")));
-```
+# Both with failure on issues
+mvn verify -Dspotbugs.failOnError=true -Dpmd.failOnViolation=true
+
+# Single module
+mvn spotbugs:check pmd:check -pl qqq-backend-core -DskipTests
 
-**OAuth2 Customizer:**
-```java
-new OAuth2AuthenticationModule()
-   .withCustomizer(new QCodeReference(MyCustomizer.class));
+# View SpotBugs GUI
+mvn spotbugs:gui -pl qqq-backend-core
 ```
 
-### Related Links
-- [Discussion #340 - Daily Build Log](https://github.com/orgs/QRun-IO/discussions/340)
-- [Issue #336 - QSessionStoreInterface](https://github.com/Kingsrook/qqq/issues/336)
-- [PR #280](https://github.com/Kingsrook/qqq/pull/280), [#320](https://github.com/Kingsrook/qqq/pull/320), [#321](https://github.com/Kingsrook/qqq/pull/321), [#335](https://github.com/Kingsrook/qqq/pull/335), [#337](https://github.com/Kingsrook/qqq/pull/337)
+### CircleCI Trigger (after orb release)
+```bash
+# Via tag
+git tag static-analysis/$(date +%Y%m%d) && git push origin --tags
+
+# Via API
+curl -X POST https://circleci.com/api/v2/project/gh/Kingsrook/qqq/pipeline \
+  -H "Circle-Token: $CIRCLE_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"parameters": {"run_static_analysis": true}}'
+```