Aether Style Guard

An Error Prone compiler plugin that enforces strict coding rules as guard rails for AI-generated Java code.

Overview

Aether Style Guard is an Error Prone compiler plugin that turns five stylistic conventions into compile-time diagnostics, so that AI-assisted Java code comes out uniform, self-documenting, and easy to review. Every rule the plugin enforces is motivated by a real pain point with AI-generated code: implicit field accesses, missing nullness annotations, parameters that the model "forgets" to mark final, non-void methods without a nullability contract, and Javadoc that is either missing or half-finished.

The project dogfoods every single rule through its own selfcheck Maven profile. The plugin builds, installs locally, and then rebuilds its own source tree through itself as a final sanity check before any release goes out.

Note

Aether Style Guard is a member of the Aether Framework family of Java tooling. Its flagship sibling is Aether Datafixers, from which this project inherits its release process, build layout, and contributor conventions.

📋 Table of Contents

• Quick Start
• The Five Rules
• Installation
• Configuration
• Dogfooding
• Why AI Guard Rails?
• Building from Source
• Contributing
• Security
• License

🚀 Quick Start

1. Add the plugin to your build

Maven

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <configuration>
        <compilerArgs>
          <arg>-XDcompilePolicy=simple</arg>
          <arg>-Xplugin:ErrorProne</arg>
        </compilerArgs>
        <annotationProcessorPaths>
          <path>
            <groupId>com.google.errorprone</groupId>
            <artifactId>error_prone_core</artifactId>
            <version>2.36.0</version>
          </path>
          <path>
            <groupId>de.splatgames.aether.styleguard.labs</groupId>
            <artifactId>aether-style-guard</artifactId>
            <version>0.1.1</version>
          </path>
        </annotationProcessorPaths>
      </configuration>
    </plugin>
  </plugins>
</build>

2. Rebuild your project

mvn clean compile

The compiler will now surface stylistic violations as ordinary javac errors (or warnings, for the Javadoc-presence check). Most violations come with a ready-to-apply auto-fix.

3. Optionally: apply auto-fixes in place

mvn -DcompilerArgument="-XepPatchChecks:RequireThisPrefix,RequireParameterNullness,RequireFinalParameter,RequireMethodReturnNullness -XepPatchLocation:IN_PLACE" compile

🛡️ The Five Rules

Rule	Severity	Summary	Auto-Fix
RequireThisPrefix	ERROR	Every instance-field access must be qualified with this..	✅
RequireParameterNullness	ERROR	Every reference-type parameter must carry @NotNull or @Nullable.	✅
RequireFinalParameter	ERROR	Every parameter that is not reassigned inside the body must be declared final.	✅
RequireMethodReturnNullness	ERROR	Every non-void, non-primitive method return value must carry a nullness annotation.	✅
RequireJavadocPresent	WARNING	Public and protected methods should have a Javadoc comment.	–
RequireJavadocComplete	ERROR	Any Javadoc on a public or protected method must document every value parameter and the return value.	–

The Javadoc rule is split across two checkers because Error Prone allows only one severity per @BugPattern. Together they enforce: "if you write Javadoc, write it completely; if you do not write any, that is at least worth a warning."

Recognised nullness annotations

The plugin accepts nullness annotations from every major Java ecosystem, so projects can keep whatever they already use:

• org.jetbrains.annotations.NotNull / Nullable (default for auto-fixes)
• jakarta.annotation.Nonnull / Nullable
• javax.annotation.Nonnull / Nullable
• jakarta.validation.constraints.NotNull, javax.validation.constraints.NotNull
• org.jspecify.annotations.NonNull / Nullable
• org.checkerframework.checker.nullness.qual.NonNull / Nullable
• org.springframework.lang.NonNull / Nullable
• edu.umd.cs.findbugs.annotations.NonNull / Nullable
• androidx.annotation.NonNull / Nullable, android.support.annotation.NonNull / Nullable
• lombok.NonNull

📦 Installation

Maven

<dependency>
  <groupId>de.splatgames.aether.styleguard.labs</groupId>
  <artifactId>aether-style-guard</artifactId>
  <version>0.1.1</version>
</dependency>

Gradle (Groovy / Kotlin)

// Groovy
errorprone 'de.splatgames.aether.styleguard.labs:aether-style-guard:0.1.1'

// Kotlin
errorprone("de.splatgames.aether.styleguard.labs:aether-style-guard:0.1.1")

The plugin is provided-scope at consumer build time: it participates in compilation through the annotationProcessorPath of the maven-compiler-plugin and ships no runtime code to the consuming application.

⚙️ Configuration

Every rule ships with sensible defaults. Two settings can be overridden per build via standard Error Prone flags:

Flag	Purpose	Default
-XepOpt:AetherStyleGuard:NotNull=<fqn>	FQN of the @NotNull annotation inserted by auto-fixes	org.jetbrains.annotations.NotNull
-XepOpt:AetherStyleGuard:Nullable=<fqn>	FQN of the @Nullable annotation used alongside the @NotNull choice	org.jetbrains.annotations.Nullable

Rules can be individually silenced with standard Error Prone syntax, e.g. -Xep:RequireJavadocPresent:OFF.

🍲 Dogfooding

This project uses its own plugin to lint its own source tree. The selfcheck Maven profile re-compiles src/main/java with aether-style-guard active, so any drift between the rules and the plugin's own code immediately becomes a build failure.

# Step 1: install the plugin locally
mvn clean install

# Step 2: rebuild the sources through the plugin
mvn compile -Pselfcheck

A green selfcheck is part of the release checklist in RELEASE.md.

🧠 Why AI Guard Rails?

AI-generated Java code is usually syntactically correct but stylistically drifty: one file is sprinkled with this., the next one is not; one method carries @NotNull on its parameters, the next one omits it; one constructor declares every parameter final, the next one relies on implicit effective-finality. This inconsistency is cheap to fix after the fact but expensive to review when it accumulates across a codebase.

Aether Style Guard collapses those decisions into five compile-time rules with auto-fixes, so the AI model can emit whatever it likes and the compiler rewrites it into the house style automatically. The result is a codebase where every file reads as if it came from the same author.

🔨 Building from Source

Requirements: Java 17+, Maven 3.9.5+

# Build and install locally
mvn clean install

# Run unit tests only
mvn test

# Run the selfcheck (dogfood the plugin)
mvn compile -Pselfcheck

# Build a signed release candidate (requires GPG config)
mvn clean verify -Prelease

🤝 Contributing

We welcome contributions of all kinds - new checkers, bug fixes, documentation improvements, and discussions.

Please read our Contributing Guide before submitting a pull request. This project follows the Contributor Covenant Code of Conduct. For AI-assisted contributions, please review our AI Usage Guidelines - especially relevant for this project, since it exists to set the tone for what good AI-assisted Java should look like.

🔒 Security

All release artifacts are GPG-signed and published to Maven Central. The project uses automated security scanning via CodeQL, OWASP Dependency-Check, and Dependabot.

To report a vulnerability, see our Security Policy.

📄 License

This project is licensed under the MIT License.

Copyright (c) 2025-2026 Splatgames.de Software and Contributors.