Support package-info.java

[arey]

The plugin looks like to not taking account @NullUnmarked annotations declared at the package-info.java level. Isn't it?

@NullUnmarked
package com.myproject.mapper;

import org.jspecify.annotations.NullUnmarked;

[mk868]

Yes, it's aware of the annotation @NullUnmarked on package-info.java.
The requirespecifiednullness rule analyzes the context and uses it to determine whether nullness is considered specified or unspecified for types within that scope.

So, for the following code, requireSpecifiedNullness should report an error when nullness is unspecified:

package abc;

public class Model {
  private String name;
}

module-info.java	abc/package-info.java	Model#name type nullness
not annotated / doesn't exist	not annotated / doesn't exist	unspecified -> ERROR
not annotated / doesn't exist	@NullMarked	specified -> OK
not annotated / doesn't exist	@NullUnmarked	unspecified -> ERROR
@NullMarked	not annotated / doesn't exist	specified -> OK
@NullMarked	@NullMarked	specified -> OK
@NullMarked	@NullUnmarked	unspecified -> ERROR

Can you please describe your use case?

[arey]

Perhaps I hadn't understood the use of the @NullUnmarked annotation.

But I've the same behavior with the @NullMarked annotation declared at the package-info.java level. Here is my use case:

module-info.java	abc/package-info.java	Model#name type nullness
not annotated / doesn't exist	@NullMarked	specified -> OK

@NullMarked
package com.myproject.domain;

import org.jspecify.annotations.NullMarked;

[INFO] --- nullaudit:0.5.0:check (default) @ domain ---
[ERROR] 1 issues found.
[ERROR] com.myproject.domain.MyClass: Missing @NullMarked annotation on the class.

[mk868]

I see, in your case I think you can skip the requireNullMarked rule:

 <plugin>
      <groupId>eu.soft-pol.lib.nullaudit</groupId>
      <artifactId>nullaudit-maven-plugin</artifactId>
      <version>0.5.0</version>
      <configuration>
        <rules>
          <!-- <requireNullMarked/> don't force to put @NullMarked on classes -->
          <requireSpecifiedNullness/>
          <verifyJSpecifyAnnotations/>
        </rules>
         <!-- ... -->
      </configuration>
<!-- ... -->

The requireNullMarked was created because some projects require the @NullMarked annotation to be explicitly placed on all classes.
Placing this annotation manually on each class is useful for migration - we can systematically (in small Pull Request 5-10 files) append nullness information to the classes in the project and finally require that all classes be annotated by @NullMarked.

But this is hardly your use case, so I think you can skip the requireNullMarked rule.

BTW. I'm still working on documenting these rules correctly + describing typical use-cases

[mk868]

Hmm, I can also extend requireNullMarked to expect @NullMarked not only on classes, but also in other places:

potential configuration I can add:

<requireNullMarked>
  <!-- <annotationOn>CLASSES</annotationOn> by default -->
  <annotationOn>PACKAGES</annotationOn> <!-- require to put @NullMarked annotation on all package-info.java files -->
</requireNullMarked>

I guess it would fit your needs

[arey]

In my existing legacy basecode, with the NullAway plugin, I'm combining both @NullUnmarked and @NullMarked packaged. @NullMarked in first (95% of the packages). More rarely, @NullUnmarked is used for instance on JPA entity packages with getter/setter and no constructor.
Did nullaudit provide any kind of configuration? I could test it.

[mk868]

At this point, there is a configuration parameter <exclusionsFile> that points to a file with specific classes/packages excluded from analysis.
This file is helpful when:

• We don't want to run the analysis instantly on all existing code - we can put all legacy classes in this file and then gradually migrate them to JSpecify
• Some classes should not be checked because we have no control over them (e.g., they are auto-generated)
• we are aware that the classes have Unspecified nullness, and this is fine for us - we can exclude these classes from analysis

I updated the multi-module example to use <exclusionsFile>.

Your configuration may look like the following:

pom.xml

 <plugin>
      <groupId>eu.soft-pol.lib.nullaudit</groupId>
      <artifactId>nullaudit-maven-plugin</artifactId>
      <version>0.5.0</version>
      <configuration>
        <rules>
          <requireSpecifiedNullness>
            <exclusionsFile>nullaudit-ignored.txt</exclusionsFile>
          </requireSpecifiedNullness>
          <verifyJSpecifyAnnotations/>
        </rules>
         <!-- ... -->
      </configuration>
<!-- ... -->

nullaudit-ignored.txt

# Allow unspecified nullness in domain classes
com.myproject.domain.*

About Exclusions File format:

• Each non-empty line defines one class or pattern.
• Leading and trailing whitespace is ignored.
• Lines starting with # are treated as comments and ignored.
• Wildcards * and ** are supported similarly to Ant-style patterns.