Copilot instructions

1---
2description: Micronaut Development Guide
3author: Cédric Champeau
4version: 1.0
5globs: ["**/*.java", "**/*.kts", "**/*.xml"]
6---
7 
8# Micronaut Project Development Guide
9 
10## Project Overview
11 
12This project is a Micronaut module which is part of the Micronaut Framework, a modern, JVM-based, full-stack framework for building modular, easily testable microservice and serverless applications.
13 
14The description of what this project is doing can be found in the `gradle.properties` file under the `projectDesc` key.
15 
16This repository does not represent an actual application; its modules are designed to be used as dependencies by applications.
17The root project MUST NOT contain any code: it is a parent project which coordinates the build and supplies documentation.
18 
19⚠️ CRITICAL: DO NOT USE attempt_completion BEFORE TESTING ⚠️
20 
21## Command Conventions
22 
23- You MUST run all Gradle commands (except testing ones) with the quiet option to reduce output:
24    - Do NOT use: `--stacktrace`, `--info` (excessive output will not fit the context)
25- You MUST run all Gradle testing commands without the `-q` option, since that will suppress the output result of each test.
26- Gradle project names are prefixed with `micronaut-`. For example, directory `mylib` maps to Gradle project `:micronaut-mylib`.
27- You MUST run Gradle with the Gradle wrapper: `./gradlew`.
28- Gradle project names prefixed with `test-` or `test-suite` are not intended for users: they are functional tests of the project
29 
30## Main Development Tasks:
31 
32- Compile (module): `./gradlew -q :<module>:compileTestJava`
33- Test (module): `./gradlew :<module>:test`
34- Checkstyle (aggregate task): `./gradlew -q cM`
35    - Note: `cM` is the canonical Checkstyle runner defined in build logic to validate Checkstyle across the codebase.
36    - Note: you MUST NOT introduce new warnings. You SHOULD fix warnings in code that you have modified.
37- Spotless (check license headers/format): `./gradlew -q spotlessCheck`
38- Spotless (auto-fix formatting/headers): `./gradlew -q spotlessApply` (MUST be used to fix violations found by `spotlessCheck`)
39 
40## Code style
41 
42You SHOULD prefer modern Java idioms: records, pattern matching, sealed interfaces/classes, `var` for local variables.
43You MUST NOT use fully qualified class names unless there is a conflict between 2 class names in different packages.
44You MUST annotate the code with nullability annotations (`org.jspecify.annotations.Nullable`, `org.jspecify.annotations.NonNull`).
45You MUST NOT use reflection: Micronaut is a reflection-free framework tailored for integration with GraalVM.
46You MUST use `jakarta.inject` for dependency injection, NOT `javax.inject`.
47 
48## Binary compatibility
49 
50Micronaut projects are intended to be used in consumer applications and therefore follow semantic versioning. As a consequence:
51- You MUST NOT break any public facing API without explicit consent
52- You SHOULD run the `./gradlew japiCmp` task to get a report about binary breaking changes
53- You SHOULD reduce the visibility of members for non-user-facing APIs.
54- You MUST annotate non-user facing APIs with `@io.micronaut.core.annotation.Internal`
55 
56## Implementation Workflow (Required Checklist)
57 
58You MUST follow this sequence after editing source files:
59 
601) Compile affected modules
61    - `./gradlew -q :<module>:compileTestJava :<module>:compileTestGroovy`
62 
632) Run targeted tests first (fast feedback)
64    - `./gradlew :<module>:test --tests 'pkg.ClassTest'`
65    - `./gradlew :<module>:test --tests 'pkg.ClassTest.method'` (optional)
66 
673) Run full tests for all affected modules
68    - `./gradlew :<module>:test`
69 
704) Static checks
71    - Checkstyle: `./gradlew -q cM`
72 
735) (Optional) If, and only if you have created new files, you SHOULD run
74    - Spotless check: `./gradlew -q spotlessCheck`
75    - If Spotless fails: `./gradlew -q spotlessApply` then re-run `spotlessCheck`
76    - You MUST NOT add new license headers on existing files: only focus on files you have added
77 
786) Verify a clean working tree
79    - You SHOULD ensure no unrelated changes are pending before proposing changes.
80    - Use `git_status` to verify the working tree:
81```xml
82      <use_mcp_tool>
83       <server_name>mcp-server-git</server_name>
84       <tool_name>git_status</tool_name>
85       <arguments>
86           {
87           "repo_path": "/home/cchampeau/DEV/PROJECTS/micronaut/micronaut-langchain4j" // adjust absolute path if necessary
88           }
89       </arguments>
90      </use_mcp_tool>
91```
92 
93## Documentation Requirements
94 
95- You MUST update documentation when necessary, following the project’s documentation rules in `.clinerules/docs.md`.
96- Before writing code, you SHOULD analyze relevant code files to get full context, then implement changes with minimal surface area.
97- You SHOULD list assumptions and uncertainties that need clarification before completing a task.
98- You SHOULD check project configuration/build files before proposing structural or dependency changes.
99 
100## Context7 Usage (Documentation and Examples)
101 
102You MUST use Context7 to get up-to-date, version-specific documentation and code examples for frameworks and libraries.
103 
104Preferred library IDs:
105- Micronaut main docs: `/websites/micronaut_io`
106- Micronaut Test: `/websites/micronaut-projects_github_io_micronaut-test`
107- Micronaut Oracle Cloud: `/websites/micronaut-projects_github_io_micronaut-oracle-cloud`
108- OpenRewrite: `/openrewrite/rewrite-docs`
109 
110Example (fetch docs for a topic):
111```xml
112<use_mcp_tool>
113    <server_name>context7-mcp</server_name>
114    <tool_name>get-library-docs</tool_name>
115    <arguments>
116        {
117            "context7CompatibleLibraryID": "/openrewrite/rewrite-docs",
118            "topic": "JavaIsoVisitor"
119        }
120    </arguments>
121</use_mcp_tool>
122```
123 
124For other libraries, you MUST resolve the library ID first:
125```xml
126<use_mcp_tool>
127    <server_name>context7-mcp</server_name>
128    <tool_name>resolve-library-id</tool_name>
129    <arguments>
130        {
131            "libraryName": "Mockito"
132        }
133    </arguments>
134</use_mcp_tool>
135```
136 
137## Dependency Management (Version Catalogs)
138 
139- Main dependencies are managed in the Gradle version catalog at `gradle/libs.versions.toml`.
140- You MUST use catalogs when adding dependencies (avoid hard-coded coordinates/versions in module builds).
141 
142Adding a new dependency (steps):
1431) Choose or add the version in the appropriate catalog (`libs.versions.toml`).
1442) Add an alias under the relevant section (e.g., `libraries`).
1453) Reference the alias from a module’s `build.gradle.kts`, for example:
146    - `implementation(libs.some.library)`
147    - `testImplementation(testlibs.some.junit)`
1484) Do NOT hardcode versions in module build files; use the catalog entries.
149 
150You SHOULD choose the appropriate scope depending on the use of the library:
151    - `api` for dependencies which appear in public signatures or the API of a module
152    - `implementation` for dependencies which are implementation details, only used in the method bodies for example
153    - `compileOnly` for dependencies which are only required at build time but not at runtime
154    - `runtimeOnly` for dependencies which are only required at run time and not at compile time
155 
156## Build logic
157 
158Micronaut projects follow Gradle best practices, in particular usage of convention plugins.
159Convention plugins live under the `buildSrc` directory.
160 
161You MUST NOT add custom build logic directly in `build.gradle(.kts)` files.
162You MUST implement build logic as part of convention plugins.
163You SHOULD avoid build logic code duplication by moving common build logic into custom convention plugins.
164You SHOULD try to prefer composition of convention plugins.
165 
166## Key Requirements
167 
168You MUST confirm all the following BEFORE using `attempt_completion`:
169 
170- Changes compile successfully (affected modules)
171- Targeted tests pass
172- Full tests for affected modules pass
173- Checkstyle (`cM`) passes
174- Spotless (`spotlessCheck`) passes (apply fixes if needed)
175- Documentation updated when necessary
176- Working tree is clean (no unrelated diffs)
177 
178If ANY item is “no”, you MUST NOT use `attempt_completion`.
179While you SHOULD add new files using `git add`, you MUST NOT commit (`git commit`) files yourself.
180