Skip to content

Text-parser annotation-resolution gaps found by the binary-stub diff harness #1861

Description

@wmdietl

An open follow-up task for #1853:

Widening BinaryStubDiffChecker.checkerAnnotationNames to compare all declaration
annotations (instead of only org.checkerframework.*) surfaced 7 mismatch sites on the
JDK 21 annotated JDK. All are cases where the text parser drops an annotation that the
binary writer (running with the full JDK on its build-time classpath) correctly resolves
and keeps
— i.e., text-parser resolution gaps, not binary-path bugs. Documented in the
checkerAnnotationNames javadoc (commit 80c6548a); the widening was reverted and the
filter kept.

Remaining problems, by category:

  1. Meta-annotations on java.lang annotation declarations dropped.
    @Retention/@Target written on the declarations of java.lang.Override,
    java.lang.Deprecated, and java.lang.SuppressWarnings in the annotated JDK are
    dropped by AnnotationFileParser (not imported, not covered by the unconditional
    java.lang seeding), while the binary path keeps them.
  2. Static-imported annotations dropped. @DefinedBy on
    com.sun.tools.javac.file.JavacFileManager.setPathFactory(..) is reachable only via a
    static import; the text parser's resolution does not cover this position. (Note: the
    sibling issue for constants in annotation values was fixed on the binary side in
    2aa3c956; this is the annotation-name case, and here the text parser is the
    deficient side.)
  3. JDK-internal meta-annotations dropped.
    @Retention/@Target/jdk.internal.javac.PreviewFeature on
    ClientCodeWrapper.Trusted, LambdaForm.Compiled, and Tree.Kind.DEFAULT_CASE_LABEL
    — never imported by the stub source, so the text parser never resolves them.
  4. Verification gap for non-CF annotations. Because of quirks 1–3, the diff harness
    compares only org.checkerframework.* declaration annotations. If org.jspecify
    annotations enter the annotated JDK, they will go unverified by the harness — a real
    gap, since copyAndMinimizeAnnotatedJdkFiles already deliberately preserves
    org.jspecify content.

None of the dropped names are currently consumed by any checker from a stub file, so today
the asymmetry is benign. Follow-up options: (a) extend AnnotationFileParser's resolution
(meta-annotations on annotation declarations; static-imported annotation names) so the
filter can be widened, or (b) accept the gaps but widen the filter to an allowlist that
includes org.jspecify before jspecify annotations land in the JDK.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions