updated coding standards
All checks were successful
Build, test and publish / verify (push) Successful in 4m43s
All checks were successful
Build, test and publish / verify (push) Successful in 4m43s
This commit is contained in:
54
specs/S7-review-signals.txt
Normal file
54
specs/S7-review-signals.txt
Normal file
@@ -0,0 +1,54 @@
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/scheduling/GroupRequirement.java:3 recordComponents=2 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/scheduling/SchedulingInput.java:5 recordComponents=4 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/scheduling/SchedulingResult.java:7 recordComponents=2 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/DancerRequest.java:8 recordComponents=2 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/DancerView.java:6 recordComponents=3 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/DayPartRequest.java:7 recordComponents=2 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/DayPartView.java:9 recordComponents=3 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/ErrorView.java:6 recordComponents=1 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/GroupRequest.java:12 recordComponents=5 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/GroupView.java:13 recordComponents=7 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/SchedulingView.java:3 recordComponents=2 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/SchoolRequest.java:5 recordComponents=1 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/SchoolView.java:11 recordComponents=5 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/ShowRequest.java:13 recordComponents=3 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/ShowView.java:13 recordComponents=4 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Group.java:9 recordComponents=8 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/GroupDetails.java:9 recordComponents=5 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/ImportPreview.java:3 recordComponents=6 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Part.java:9 recordComponents=3 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Performance.java:10 recordComponents=4 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Person.java:5 recordComponents=3 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:27 recordComponents=7 (manual design review)
|
||||
DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Trainer.java:3 recordComponents=2 (manual design review)
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/DanceGroup.java:18 fanOut=16.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/DanceSchool.java:16 fanOut=16.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/DanceGroupResource.java:28 fanOut=21.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/DanceSchoolResource.java:27 fanOut=20.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/DancerResource.java:27 fanOut=20.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/SchoolSnapshotResource.java:26 fanOut=25.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/ShowResource.java:32 fanOut=25.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/GroupView.java:21 parameters=7.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolManagementService.java:102 cyclomatic=8.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolManagementService.java:282 executableLines=33.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolManagementService.java:282 parameters=5.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolManagementService.java:35 fanOut=35.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolManagementService.java:35 publicMethods=28.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:136 executableLines=37.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:174 executableLines=35.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:27 fanOut=29.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:35 parameters=7.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:42 executableLines=41.0
|
||||
REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/solver/OrToolsSchedulingEngine.java:20 fanOut=17.0
|
||||
REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchedulingTest.java:29 fanOut=22.0
|
||||
REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolManagementResourceTest.java:123 executableLines=44.0
|
||||
REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolManagementResourceTest.java:168 executableLines=38.0
|
||||
REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolManagementResourceTest.java:26 executableLines=39.0
|
||||
REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolSnapshotResourceTest.java:16 executableLines=40.0
|
||||
REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolSnapshotTest.java:30 fanOut=19.0
|
||||
REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolSnapshotTest.java:56 executableLines=32.0
|
||||
REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SnapshotCollectionsTest.java:26 fanOut=22.0
|
||||
REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/service/SchedulingServiceTest.java:28 fanOut=28.0
|
||||
REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/service/SchedulingServiceTest.java:29 executableLines=32.0
|
||||
REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/service/SchedulingServiceTest.java:62 executableLines=38.0
|
||||
WAIVER agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Group.java:19 parameters=8.0 Maintainer approved in the S7 implementation conversation: preserve the eight-component version-2 JSON shape while defensively copying styles and dancerIds.
|
||||
113
specs/S7-validation.md
Normal file
113
specs/S7-validation.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# S7 implementation and validation evidence
|
||||
|
||||
Status: IN_REVIEW — implementation complete; awaiting project review.
|
||||
Date: 2026-10-30. Environment: Ubuntu amd64, OpenJDK 25.0.4.1, Maven 3.9.16.
|
||||
|
||||
## Delivered changes
|
||||
|
||||
Enforcement/configuration: root coding standards and agent discovery instructions;
|
||||
project review companion (upstream skills unchanged); individually selected
|
||||
Checkstyle 12.3.1 checks; PMD/CPD 7.28.0 with targeted measurements and regression
|
||||
fixtures; JaCoCo 0.8.14 with exact line-count gates; verify integration; Docker
|
||||
build inputs; CI instrumentation, merge and diagnostic retention. No broad
|
||||
standards/coverage exclusions or unrelated rule bundles were introduced.
|
||||
|
||||
Migration: explicit imports and visibility, required finality and explicit types;
|
||||
an explicit collaborator constructor for scheduling tests while preserving CDI field injection and the public no-argument constructor; smaller snapshot-restoration,
|
||||
import-rebuilding, solver and validation methods; smaller HTTP test helpers;
|
||||
null-tolerant defensive collection copies for records, including both levels of
|
||||
solver assignments. Existing entity classes retain their mutation, Lombok and
|
||||
framework contracts. API paths, payloads, snapshot version and persistence behavior
|
||||
are unchanged. Enforcement and migration can be reviewed separately by path.
|
||||
|
||||
## Scope, tools and measurements
|
||||
|
||||
58 handwritten production files and 9 handwritten test files are checked.
|
||||
Generated target output, frontend code and Java helpers outside the backend are
|
||||
outside that standards scope. All handwritten production packages participate in
|
||||
coverage, including DTOs and configuration. JaCoCo's generated-member filtering is
|
||||
used; no handwritten class/package exclusions are configured.
|
||||
|
||||
See CODING_STANDARDS.md for complete targets, strict thresholds, algorithm options,
|
||||
manual rules, scope and standalone commands. The full current metrics report is
|
||||
`agiledancers-be/target/standards/report.txt`. Production CPD currently reports
|
||||
**0%** duplicated code lines at its 100-token minimum. Test duplication is not gated.
|
||||
|
||||
The selected PMD finality rules complement custom checks. PMD cyclomatic and
|
||||
cognitive visitors are scoped explicitly: lambdas contribute, nested/local type
|
||||
methods are independent, and no aggregate class complexity gate is introduced.
|
||||
Resolved collaborator identity includes qualifier values/defaults and inherited
|
||||
generic type substitution. Exact metric waivers are supported and regression tested;
|
||||
`tooling/standards/waivers.tsv` records the sole approved waiver: the exact
|
||||
eight-parameter Group constructor needed to preserve its version-2 JSON shape.
|
||||
|
||||
## Reproducible validation
|
||||
|
||||
Set JAVA_HOME to JDK 25 and run from the repository root.
|
||||
|
||||
| Command/check | Result |
|
||||
| --- | --- |
|
||||
| `mvn -Dformat.mode=check clean verify` | Passed: 38 backend tests, 17 checker tests, standards checks and the exact backend coverage gate. |
|
||||
| `mvn -pl agiledancers-be package -DskipTests` | Passed; Quarkus packaged app successfully produced and subsequently exercised by Playwright. |
|
||||
| `mvn -f tooling/standards/pom.xml test exec:java` | 17 checker tests passed; no unwaived blocking violations. |
|
||||
| `java tooling/coverage/Coverage.java agiledancers-be/target/site/jacoco/jacoco.xml` | Clean backend-only line gate passed: 791 covered / 818 total = 96.69926650366749%. |
|
||||
| `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/opt/google/chrome/chrome npm run e2e` in frontend | Both browser tests passed against the packaged instrumented backend. |
|
||||
| Pinned CLI `dump --address 127.0.0.1 --destfile agiledancers-be/target/playwright.exec` | Successfully collected execution data from the agent's TCP server. |
|
||||
| `mvn -pl agiledancers-be jacoco:merge@combined jacoco:report@combined-report exec:exec@combined-coverage` | Passed with matching clean-build application classes: combined 791/818 lines, 96.69926650366749%. |
|
||||
| `java ci/Ci.java test` | 17 CI orchestration tests passed. |
|
||||
| `git diff --check` | Passed. |
|
||||
|
||||
Both local and combined branch reports contain 195 covered / 257 total branches
|
||||
(75.87548638132296%); branches have no blocking percentage. Browser coverage is
|
||||
successfully collected and merged, but does not add uncovered lines in this run.
|
||||
Local and combined HTML/XML/CSV reports are under `agiledancers-be/target/site`.
|
||||
Execution data is in `target/jacoco.exec`, `target/playwright.exec` and
|
||||
`target/jacoco-combined.exec` within the backend module. CI copies these reports,
|
||||
execution data and checker results into its retained diagnostics. Local validation
|
||||
exercised collection and merge; a remote Gitea publication run was not performed.
|
||||
|
||||
The checker fixtures cover strict complexity, length, parameter, nesting,
|
||||
inheritance and dependency boundaries; implicit/compact record constructors;
|
||||
lambda/nested-type scope; comments/brace lines; distinct type fan-out; nontrivial
|
||||
accessors; qualifiers, repeated and inherited injection; exact waivers; parser
|
||||
failure diagnostics; report-only behavior; CPD occurrence/overlap accounting and
|
||||
test exclusion; and the unrounded 80% line gate, including a near miss.
|
||||
|
||||
## Retained review signals
|
||||
|
||||
`S7-review-signals.txt` records the current individual REVIEW and DESIGN entries.
|
||||
The following assessment covers every retained review-signal group. The approved
|
||||
constructor waiver is documented separately below.
|
||||
|
||||
| Signal/location | Assessment and reason retained |
|
||||
| --- | --- |
|
||||
| DanceGroup and DanceSchool fan-out 16 | Domain collection/entity references and explicitly used Lombok annotations are intrinsic to these mutable aggregates. Converting them to records would break their mutation/inheritance contracts. |
|
||||
| Five REST resources, fan-out 20–25 | HTTP annotations, response/request types and service/domain mapping account for the references. These are thin adapters; splitting them to reduce annotation counts would obscure endpoint ownership. |
|
||||
| GroupView and SchoolSnapshot compact constructors, 7 parameters | Their components preserve existing JSON contracts. Constructors only protect collections and are within the allowed constructor limit. |
|
||||
| SchoolManagementService fan-out 35, public methods 28 | One shared synchronization boundary owns in-memory aggregate writes and scheduling revisions. Splitting state/locks needs its own concurrency design; the class passes blocking length/dependency limits. |
|
||||
| validateAssignments cyclomatic 8 | Independent input/result guards and required-appearance validation are explicit and tested; per-part validation has already been extracted. It remains below the blocking limit. |
|
||||
| updateShow, 33 lines and 5 parameters | Retains assignments by matching daypart keys before replacing the aggregate. Keeping the transaction visible and preserving its existing signature is preferable to artificial wrappers; both blocking limits pass. |
|
||||
| SchoolSnapshot fan-out 29; of 41 lines, restoreGroups 37, restoreShows 35 | Each method performs one graph conversion phase. Explicit type/reference checks protect imported data and preserve assignment identity. Refactoring has removed the over-limit monolithic restore method. |
|
||||
| Solver fan-out 17 | OR-Tools types are confined to this adapter and its dedicated helpers. Further indirection would spread solver details without improving the domain boundary. |
|
||||
| SchedulingTest, SchoolSnapshotTest, SnapshotCollectionsTest and SchedulingServiceTest fan-out | These behavior tests intentionally exercise multiple collaborating models, services, ports, exceptions and assertions. Production architecture remains covered separately by ArchUnit. |
|
||||
| HTTP, snapshot and scheduling test methods at 32–44 lines | Arrange/action/assert and try/finally cleanup remain together. Repeated setup was extracted where methods exceeded 50 physical code lines; retained methods pass all blocking limits. |
|
||||
| All DESIGN record-component entries | Request/view/snapshot/domain records model existing named contracts; their sizes are not automatically gated. Mutable components are copied, including both Group lists under its approved constructor waiver. Framework-backed mutable entities remain classes. |
|
||||
|
||||
## Approved compatibility decisions
|
||||
|
||||
The maintainer approved both proposals in the S7 implementation conversation:
|
||||
|
||||
1. `GroupDetails` groups category, type, age bounds and styles. The Java signatures
|
||||
of `DanceGroupService.add`, `SchoolManagementService.createGroup` and
|
||||
`updateGroup` now take 3, 2 and 3 parameters respectively. All callers were
|
||||
migrated. REST endpoints, JSON payloads and snapshot version remain unchanged.
|
||||
The record copies its styles, and service construction takes a mutable copy
|
||||
for the domain group; regression coverage verifies later style edits still work.
|
||||
2. The explicit eight-component `service.model.Group` constructor defensively
|
||||
copies styles and dancer IDs while preserving null values for existing import
|
||||
validation. Its sole waiver matches the fully resolved constructor signature,
|
||||
metric and exact retained value 8. The agreement and reason are recorded in
|
||||
`tooling/standards/waivers.tsv` and the result remains visible as `WAIVER`.
|
||||
|
||||
There are no parameter waivers for the three service methods, blanket suppressions
|
||||
or weakened thresholds. The completed specification resides in `specs/in_review`.
|
||||
@@ -1,6 +1,6 @@
|
||||
# S7 — Backend coding standards
|
||||
|
||||
Status: REFINED
|
||||
Status: IN_REVIEW
|
||||
|
||||
Shared understanding confirmed after the grill-me review.
|
||||
|
||||
@@ -176,21 +176,21 @@ exactly at a blocking limit passes.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] CODING_STANDARDS.md contains all agreed rules and preserves frontend guidance.
|
||||
- [ ] Agent and project code-review instructions enforce discovery and review of
|
||||
- [x] CODING_STANDARDS.md contains all agreed rules and preserves frontend guidance.
|
||||
- [x] Agent and project code-review instructions enforce discovery and review of
|
||||
these standards without modifying upstream skills.
|
||||
- [ ] Pinned tools, configurations and targeted checks implement the exact agreed
|
||||
- [x] Pinned tools, configurations and targeted checks implement the exact agreed
|
||||
metrics and identify manual-only rules.
|
||||
- [ ] Verify and standalone checks report actionable blocking failures and review
|
||||
- [x] Verify and standalone checks report actionable blocking failures and review
|
||||
signals; CI prevents publication after a failure.
|
||||
- [ ] Representative violations demonstrate that their checks fail, including
|
||||
- [x] Representative violations demonstrate that their checks fail, including
|
||||
relevant threshold boundaries and custom measurement semantics.
|
||||
- [ ] Existing handwritten backend production and test code passes all blocking
|
||||
- [x] Existing handwritten backend production and test code passes all blocking
|
||||
rules; retained review signals and approved waivers are documented.
|
||||
- [ ] Local backend tests and combined CI coverage meet the agreed line-coverage
|
||||
- [x] Local backend tests and combined CI coverage meet the agreed line-coverage
|
||||
gates; line and branch reports are available.
|
||||
- [ ] Clean verification and behavior-preservation tests pass after migration.
|
||||
- [ ] Evidence records tool versions, commands, scope, exclusions, metric and
|
||||
- [x] Clean verification and behavior-preservation tests pass after migration.
|
||||
- [x] Evidence records tool versions, commands, scope, exclusions, metric and
|
||||
coverage reports, approved waivers and verification results.
|
||||
|
||||
## Implementation handoff
|
||||
@@ -198,3 +198,14 @@ exactly at a blocking limit passes.
|
||||
This specification records the agreed design. Updating it does not implement
|
||||
checks, change agent instructions, refactor application code or establish current
|
||||
coverage. Those are implementation work, with evidence required above.
|
||||
|
||||
## Implementation evidence
|
||||
|
||||
Implementation and verification are recorded in `specs/S7-validation.md`; retained
|
||||
review signals and the sole approved waiver are recorded in
|
||||
`specs/S7-review-signals.txt` and `tooling/standards/waivers.tsv`.
|
||||
|
||||
The maintainer approved GroupDetails-based Java service signatures and the exact
|
||||
eight-parameter Group constructor waiver in the implementation conversation.
|
||||
REST/JSON contracts remain unchanged. Clean verify and browser/combined coverage
|
||||
checks pass. The implementation is ready for project review.
|
||||
Reference in New Issue
Block a user