[WP8] Native-image / AOT: user-POJO hints uncovered + nativeTest never run in CI #185

Activity

1. shihyuho

   added the

   Task

   issue type on Jul 16, 2026
2. shihyuho

   added a parent issue on Jul 16, 2026

   • Codebase review fix plan — 2026-07-16 #172
3. github-actions

   added

   status: waiting-for-triage

   on Jul 16, 2026
4. shihyuho

   added

   type: bugSomething isn't workingSomething isn't working

   status: pending-design-work動工前需要更多的設計或研究動工前需要更多的設計或研究

   and removed

   status: waiting-for-triage

   on Jul 16, 2026
5. shihyuho commented on Jul 16, 2026

   

   shihyuho

   on Jul 16, 2026

   MemberAuthor

   More actions

   This was generated by AI during triage.

   Triage Notes - needs human

   Category: bug (primary sub-finding COR-04 is a native-image correctness defect; TEST-02 is a CI/test-coverage gap)

   Summary: In a GraalVM native image the library registers reflection hints only for its own classes, so user query POJOs and custom specification subclasses get no metadata and either silently drop all filters or fail at runtime — and no CI stage exercises the native/AOT path, so this can regress undetected.

   Current behavior:

   • SpecMapperRuntimeHints (registered as a RuntimeHintsRegistrar via the mapper module's META-INF/spring/aot.factories) registers reflection hints exclusively from Jandex indexes found at classpath*:/META-INF/spec-mapper/reflect-config.idx. The only producer of that resource is the mapper module's own jandex-maven-plugin execution, so classpath*: matches only the library's own classes.
   • User application classes are never scanned. The starter module ships no aot.factories and no RuntimeHintsRegistrar of its own (only its AutoConfiguration.imports).
   • At query time ReflectionDatabind walks the user query POJO's fields via doWithLocalFields(target.getClass(), ...) and reads them with ReflectionUtils.makeAccessible + getField; SimpleSpecification.newSpec instantiates custom SimpleSpecification subclasses reflectively via accessibleConstructor(...).newInstance(...). In a native image without hints for those user types, getDeclaredFields returns nothing (spec built from zero fields → filters silently dropped → every row returned) or a MissingReflectionRegistrationError is thrown, and custom @Spec(value=...) classes fail to instantiate.
   • There is no documentation anywhere in the repo (README, site/content, CONTRIBUTING) describing the META-INF/spec-mapper/reflect-config.idx contract or telling native-image users how to make their query POJOs / custom specs reachable.
   • No CI pipeline exercises the native path: the Jenkinsfile runs only make compile, make test, and matrix make test; the six GitHub workflows invoke no Maven test at all. The test-native Makefile target (mvn -PnativeTest process-classes test) and the parent pom's nativeTest profile (process-test-aot + native-maven-plugin) exist but are never invoked by any pipeline. The three JVM hint tests (SpecRuntimeHintsTest, DomainRuntimeHintsTest, AnnotationRuntimeHintsTest) only assert hint registration on the JVM — they never build or run an actual native image.

   Desired behavior:

   • Native-image applications using the starter get correct behavior for their own @Spec-annotated query POJOs and custom SimpleSpecification subclasses — either automatically, or via a clearly documented, supported mechanism the user applies.
   • The native/AOT support is protected by CI so a new subclass/annotation, a Jandex-index miss, or a GraalVM/Spring AOT upgrade cannot ship a silent native-image regression.

   Key interfaces (named types/methods):

   • SpecMapperRuntimeHints (implements org.springframework.aot.hint.RuntimeHintsRegistrar) — the registerHints(RuntimeHints, ClassLoader) method and the REFLECT_CONFIG_LOCATION constant.
   • ReflectionDatabind — the of(...) factory that calls doWithLocalFields(target.getClass(), ...) and getFieldValue(...) using ReflectionUtils.makeAccessible.
   • SimpleSpecification#newSpec(Context, Class<? extends SimpleSpecification>, String, Object) — reflective accessibleConstructor(...).newInstance(...).
   • QueryBySpecExecutor (starter) — candidate anchor for an AOT BeanFactoryInitializationAotProcessor if the auto-registration route is chosen.
   • Build/CI: parent pom nativeTest profile, Makefile test-native target, Jenkinsfile stages, .github/workflows/.

   Acceptance criteria (depend on the chosen approach — see Needs human):

   • Native-image users have a working, supported path so their query POJOs and custom spec subclasses receive reflection metadata (auto-registered by the starter, and/or documented for the user to apply).
   • If a documented-contract approach is chosen: README/site documents the META-INF/spec-mapper/reflect-config.idx mechanism (including a jandex-maven-plugin snippet) for native-image users.
   • If an auto-processor approach is chosen: the starter registers reflection hints (all MemberCategory values) for the relevant user types, verified by an AOT/hints unit test in the starter module.
   • A CI stage runs the native/AOT test path (make test-native / -PnativeTest) on at least the release Java/Spring combination, wired into whichever pipeline the maintainers designate.

   Out of scope:

   • Changing how JVM-mode reflection/databind works.
   • Broadening classpath*:/META-INF/spec-mapper/reflect-config.idx semantics for the library's own classes.

   Needs human because:

   1. COR-04 requires a design / public-contract decision. The fix has genuinely different shapes with different public-API and support implications: (a) document the reflect-config.idx contract and require users to run jandex-maven-plugin on their own modules; (b) ship an automatic AOT BeanFactoryInitializationAotProcessor in the starter; or (c) both. Option (b) is not mechanically obvious: the user query POJO type is passed as a runtime argument to SpecMapper/QueryBySpecExecutor, not declared in any repository generic signature, so "types reachable from repository QueryBySpecExecutor signatures" does not actually capture the POJOs that need hints — deciding what to scan (component-scan for @Spec fields? entity graph? user opt-in annotation?), the default on/off, and the resulting public contract is a maintainer policy call, not a self-contained coding task.
   2. TEST-02 requires CI/infrastructure sign-off and an environment the JUnit suite cannot provide. Running make test-native needs a GraalVM native-image toolchain (e.g. graalvm/setup-graalvm) and a new Jenkins/GitHub Actions stage; this is release/CI infrastructure that cannot be self-verified with plain mvn test in an isolated worktree, and which pipeline owns it (and its cost on the build matrix) is a maintainer decision. The concrete CI acceptance criteria also cannot be finalized until the COR-04 approach is chosen, since that determines what the native test must assert.
6. shihyuho commented on Jul 20, 2026

   

   shihyuho

   on Jul 20, 2026

   MemberAuthor

   More actions

   Superseded by #202 in the execution map #204, which carries the same findings (COR-04, TEST-02). This 2026-07-16 static plan is being retired in favour of that map.
7. shihyuho

   closed this as not plannedon Jul 20, 2026