auto-assert

Overview

Some classes have a contract that must hold for every method call — "must be called on the main thread", "must hold the render lock", "must not be invoked while the engine is paused". The classic fix is to copy-paste a guard call at the top of every method. It works until someone adds a new method and forgets.

auto-assert moves the guard from convention to instrumentation. You annotate the class with @AssertForAllCalls and point it at a static method on an asserter object. At build time the plugin transforms the compiled bytecode via the AGP Instrumentation API, inserting INVOKESTATIC at the entry of every qualifying method.

Installation

Add Maven Central to your plugin repositories in settings.gradle.kts:

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}

Then apply the plugin in your Android module:

plugins {
    id("com.rohittp.plugables.auto-assert") version "1.0.0"
}

No DSL configuration is required. The plugin generates the two annotation classes into build/generated/source/autoAssert/main and wires the AGP bytecode transform onto every variant.

Annotations

Two annotations are generated into the com.rohittp.plugables.autoassert package on every build. Import them like any other Kotlin annotation.

@AssertForAllCalls

Class-level. Marks a class as a Target class.

package com.rohittp.plugables.autoassert

import kotlin.reflect.KClass

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.BINARY)
annotation class AssertForAllCalls(val klass: KClass<*>, val method: String)

@NoAssert

Method-level. Opt a single method out of instrumentation.

package com.rohittp.plugables.autoassert

@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.BINARY)
annotation class NoAssert

There is no class-level @NoAssert — to opt a whole class out, simply don't annotate it with @AssertForAllCalls.

Asserter Requirements

The class supplied via klass = ... is called the Asserter. It must expose a method that matches the JVM descriptor ()V — no arguments, returns void — and be callable via INVOKESTATIC.

object ThreadAsserter {
    @JvmStatic
    fun assertMainThread() {
        check(Looper.myLooper() == Looper.getMainLooper()) {
            "Must be called on the main thread"
        }
    }
}

Built-in Skip Rules

Methods that match any of these rules are never instrumented, even on a Target class. The list mirrors the rules pioneered by FilamentScope's thread-safety instrumentation — they reflect what's almost always noise.

End-to-end Example

A renderer that must always run on the GL thread. Define the asserter, annotate the renderer, and the plugin injects the check into every host method.

import com.rohittp.plugables.autoassert.AssertForAllCalls
import com.rohittp.plugables.autoassert.NoAssert

object GlAsserter {
    lateinit var glThread: Thread

    @JvmStatic
    fun assertGlThread() {
        check(Thread.currentThread() === glThread) {
            "Must be called on the GL thread"
        }
    }
}

@AssertForAllCalls(klass = GlAsserter::class, method = "assertGlThread")
class SceneRenderer {

    fun render() { /* … */ }          // instrumented
    fun update() { /* … */ }          // instrumented

    @NoAssert
    fun dumpForLogging(): String {      // skipped — safe to call from any thread
        return "scene state…"
    }
}

After the build, the compiled bytecode of SceneRenderer looks like:

public final void render();
  Code:
     0: invokestatic  // Method GlAsserter.assertGlThread:()V
     3: /* … original method body … */

public final void update();
  Code:
     0: invokestatic  // Method GlAsserter.assertGlThread:()V
     3: /* … original method body … */

public final String dumpForLogging();
  Code:
     0: /* … original method body — no injection … */

Configuration

The autoAssert DSL block exposes a single optional property. Most projects never need to override it.

Caveats

Three intentional limitations to be aware of. All are surfaced upfront so the plugin's behaviour is predictable.

No inheritance

@AssertForAllCalls only triggers instrumentation on the class that declares it. Subclasses are not automatically Target classes — overrides and new methods on the subclass run unguarded unless that subclass also carries the annotation.

No asserter arguments

The Asserter method must be ()V. The plugin does not pass the calling class/method name. If you need that information, capture it from the JVM stack frame inside your asserter (Thread.currentThread().stackTrace) — pay the cost on failure, not on every call.

Multi-module duplicate classes

Because the annotation FQCN is fixed (com.rohittp.plugables.autoassert.AssertForAllCalls), applying the plugin to multiple Android modules in the same build — where one depends on another — will produce duplicate .class files at dex time. Apply the plugin in a single module, or in a shared base module everything else depends on.