Copilot instructions

1---
2applyTo: "**/*.java, **/pom.xml, **/.checkstyle*, **/checkstyle*.xml"
3---
4 
5## Context
6 
7This instruction file enforces Java code quality standards across all Java modules: Google Java Style Guide formatting, static analysis tooling (SpotBugs, Checkstyle, SonarLint), test coverage mandates (JaCoCo), and security vulnerability scanning (OWASP Dependency-Check). These rules apply to both legacy Spring MVC modules and modern Spring Boot modules. They complement the stack-specific instructions in `spring-boot.instructions.md` and `java-legacy.instructions.md`.
8 
9---
10 
11## Google Java Style Guide — Enforced Rules
12 
13All generated Java code must comply with the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html).
14 
15### Formatting Rules
16 
17| Rule | Value |
18|------|-------|
19| Indentation | 2 spaces (no tabs) |
20| Continuation indent | +4 spaces |
21| Column limit | 100 characters |
22| Brace style | Egyptian (K&R): opening brace on same line |
23| Braces | Always present — even for single-statement blocks |
24| Blank lines between members | 1 blank line |
25| Blank line after class opening brace | None |
26| Wildcard imports | Forbidden |
27| Static imports | Grouped first, then all others |
28| `var` | Allowed for local variables where the type is clear from the right-hand side |
29 
30### Naming
31 
32| Element | Convention | Example |
33|---------|-----------|---------|
34| Class | `UpperCamelCase` | `CustomerService` |
35| Method | `lowerCamelCase` | `findActiveCustomers` |
36| Variable | `lowerCamelCase` | `orderId` |
37| Constant | `UPPER_SNAKE_CASE` | `MAX_RETRY_COUNT` |
38| Type parameter | Single uppercase or `UpperCamelCase` + `T` | `T`, `CustomerT` |
39| Package | All lowercase, dot-separated | `com.example.order` |
40| Acronyms | Treated as words | `HttpUrl`, not `HTTPUrl`; `JsonParser`, not `JSONParser` |
41 
42### Javadoc Requirements
43 
44```java
45/**
46 * Processes a customer payment request and returns the transaction result.
47 *
48 * <p>If the customer's balance is insufficient, the transaction is declined
49 * and a {@link PaymentDeclinedException} is thrown.
50 *
51 * @param customerId the UUID of the customer making the payment
52 * @param amount the payment amount; must be positive
53 * @return the completed transaction result
54 * @throws PaymentDeclinedException if the payment cannot be processed
55 * @throws IllegalArgumentException if {@code amount} is null or non-positive
56 */
57public TransactionResult processPayment(UUID customerId, BigDecimal amount) { ... }
58```
59 
60- `@param` for every parameter
61- `@return` for every non-void method
62- `@throws` for every checked exception and significant runtime exception
63- Use `{@code ...}` for inline code references
64- Use `{@link ...}` for type references
65- Do not write Javadoc that merely restates the method signature
66 
67---
68 
69## Code Quality — Static Analysis Tools
70 
71### Checkstyle (Google Checks)
72 
73Checkstyle is configured with `google_checks.xml` (provided by the `checkstyle` library). Run locally:
74 
75```bash
76mvn checkstyle:check
77```
78 
79Common violations to eliminate before committing:
80- Line length > 100 characters
81- Missing Javadoc on public methods
82- Wildcard imports
83- Tabs instead of spaces
84- Magic numbers (use named constants)
85- Missing `@Override` annotation
86 
87### SpotBugs
88 
89SpotBugs performs bytecode-level static analysis. Run locally:
90 
91```bash
92mvn spotbugs:check
93```
94 
95SpotBugs bug categories to treat as build failures:
96 
97| Category | Examples |
98|----------|---------|
99| `CORRECTNESS` | Null dereference, infinite loop, integer overflow |
100| `SECURITY` | SQL injection, path traversal, hardcoded password |
101| `BAD_PRACTICE` | Unclosed streams, ignored return values |
102| `PERFORMANCE` | Unnecessary object creation in loops |
103 
104SpotBugs suppression — only with justification:
105 
106```java
107@SuppressFBWarnings(
108    value = "NP_NULL_ON_SOME_PATH_FROM_RETURN_VALUE",
109    justification = "findById is called after an existence check; null is impossible here"
110)
111```
112 
113### PMD (Optional)
114 
115If PMD is configured, enforce:
116- `UnusedImports`, `UnusedLocalVariable`
117- `EmptyCatchBlock` — must always have a logged message or re-throw
118- `SystemPrintln` — use SLF4J
119- `AvoidDeeplyNestedIfStmts` — extract methods instead
120 
121---
122 
123## JaCoCo — Test Coverage
124 
125Minimum thresholds enforced at build time:
126 
127| Metric | Threshold |
128|--------|----------|
129| Line coverage (business logic) | 80% |
130| Branch coverage (business logic) | 70% |
131| Line coverage (overall) | 70% |
132 
133Exclude from coverage measurement:
134- `**/*MapperImpl.java` (MapStruct generated)
135- `**/generated/**`
136- `**/*Application.java`
137- `**/*Config.java` (pure Spring config classes)
138- `**/dto/**`, `**/model/**` (pure data holders with no logic)
139 
140```xml
141<!-- In jacoco-maven-plugin configuration -->
142<excludes>
143  <exclude>**/*MapperImpl.class</exclude>
144  <exclude>**/generated/**</exclude>
145  <exclude>**/*Application.class</exclude>
146</excludes>
147```
148 
149---
150 
151## OWASP Dependency-Check
152 
153Scans all declared dependencies for known CVEs. Integrated as a Maven plugin; run locally:
154 
155```bash
156mvn dependency-check:check
157```
158 
159- **CVSS score ≥ 7.0** (High/Critical) → build fails
160- **CVSS score 4.0–6.9** (Medium) → generate report; review before merge
161- Suppressions require a `suppression.xml` entry with `<notes>` explaining the justification and a review date
162 
163---
164 
165## SonarLint Local Workflow
166 
1671. Install `sonarsource.sonarlint-vscode` extension (in `.vscode/extensions.json`)
1682. On file save, SonarLint highlights issues inline in the editor
1693. Connect to SonarQube/SonarCloud for team-wide rule synchronization:
170   - `Ctrl+Shift+P` → `SonarLint: Connect to SonarQube`
171   - Provide server URL and token
1724. Run a full file analysis: right-click → `SonarLint: Analyze All Open Files`
173 
174### Rules to Never Suppress
175 
176| Rule Key | Description |
177|----------|-------------|
178| `java:S2068` | Hardcoded credentials |
179| `java:S106` | `System.out.println` usage |
180| `java:S1481` | Unused local variable |
181| `java:S2095` | Resources must be closed |
182| `java:S3457` | Format string not properly formatted |
183| `java:S2259` | Null dereference |
184| `java:S1874` | Deprecated API usage |
185 
186---
187 
188## Pre-Commit Quality Checklist
189 
190Before every commit, verify:
191 
192- [ ] `mvn checkstyle:check` passes (zero violations)
193- [ ] `mvn spotbugs:check` passes (zero high/critical bugs)
194- [ ] `mvn test` passes (all unit tests green)
195- [ ] SonarLint shows no Blocker or Critical issues in changed files
196- [ ] No `System.out.println` in changed files
197- [ ] All public methods have Javadoc
198- [ ] No hardcoded secrets or connection strings
199 
200---
201 
202## CI Quality Gates
203 
204In CI/CD pipelines, run in this order:
205 
206```bash
207mvn verify                         # compile + unit tests + checkstyle + spotbugs + jacoco
208mvn sonar:sonar                    # SonarQube analysis
209mvn dependency-check:check         # OWASP CVE scan (may be separate pipeline step)
210mvn failsafe:integration-test      # integration tests (separate profile)
211```
212 
213The pipeline must not pass unless all quality gates are green.
214