Get started
library-api-watchdog is a set of compiler checks for library authors. It finds public API
declarations that are hard to evolve: shapes that can't change later without a breaking change for
the library's users.
Every check is on by default and reports a compilation error, except Undocumented public API, which reports a warning. Configuration changes the severity of a check or turns it off. Exemptions and internal API exempts a declaration.
What it looks like
A public data class with a mutable collection property and without KDoc gets three diagnostics at once:
Diagnostics in code examples are interactive. Hover over an underlined range to read the diagnostic and follow its link to the full documentation.
public data class Config(public val tags: MutableList<String>)
The fixed version has KDoc, a read-only collection, and a plain class.
Poko generates its equals, hashCode, and toString:
/** Immutable request configuration. */public class Config(/** Labels attached to this configuration. */public val tags: List<String>,)
Quick setup
Apply the Kotlin and Watchdog plugins and turn on explicit API mode:
plugins {kotlin("multiplatform") version "2.4.0"kotlin("library.api-watchdog") version "0.2.0"}kotlin {explicitApi() // Required to enable checks}
The plugin also works for Kotlin/JVM and Android projects.
See Configuration for more details about the setup and options.
A published library gets many diagnostics on the first run. The exemptExistingApi task exempts
every error in one run. See Adding the plugin to existing libraries for more
details.
All checks
API surface checks
- Boolean parameters in public API: Boolean value
parameters. An unnamed
trueorfalseargument doesn't have a readable meaning at the call site. - Data classes in public API: data classes. The generated
copyandcomponentNfunctions and the constructor expose the exact property list in the compiled API. - Exhaustive public API: enums and sealed hierarchies. Users can match them exhaustively, so a new entry or subtype breaks source compatibility.
- Function type aliases in public API: type aliases of function types. The alias isn't in the compiled API, so the type can't evolve into a richer abstraction later.
- Inconsistent parameter order in overloads: overloads whose same-named parameters occupy different positions. A caller can swap the arguments and don't get an error.
- Inline functions with logic: public inline functions with a body that does more than delegate. The compiler copies that body, and its bugs, into every user binary.
- Mutable collections in public API: mutable collection types in public signatures. The signature doesn't state whether user-side and library-side mutations affect each other.
- Nullable Booleans in public API: nullable
Booleantypes in public signatures. They model three states but name only two. - Open API without subclass opt-in: open or abstract classes and interfaces that any outside code can subclass without restriction.
- Pair and Triple in public API: the tuple types
PairandTriple. They don't carry any domain meaning, and their fixed shape can't evolve. - Required parameters after optional ones: required parameters after an optional one. A positional call must restate the earlier defaults.
- Stateful classes without equals, hashCode, and toString:
classes with a backing-field property that don't declare or inherit
equals,hashCode, andtoString. Instances compare by reference and render as an opaque default in logs and debuggers. - Subclass opt-in without markers:
@SubclassOptInRequiredannotations that don't list any marker classes. They don't restrict subclassing. - Undocumented public API: public declarations without KDoc.
- Public types from non-transitive dependencies: dependency types in public signatures that consumers don't get transitively.
- Public types marked as internal API: public signatures that expose types marked as internal API.
Java interop checks
The Java interop checks run only in JVM compilations.
- Companion function without JvmStatic:
public companion object functions without
@JvmStatic. Java callers can use them only through theCompanioninstance. - Companion property without static access:
public companion object properties whose Java-visible accessors are on the
Companioninstance instead of the outer class. - Default parameters without JvmOverloads:
functions and constructors with default parameters but without
@JvmOverloads. Java callers must pass every argument. - Kotlin-only API without JvmSynthetic: functions with a shape that only Kotlin callers can use idiomatically.
- Mangled JVM names in public API: public API with a value class in the signature. The compiler mangles the JVM name, so Java sources can't call it.
- Top-level API without JvmName: files
with public top-level declarations and without
@file:JvmName. The facade*Ktclass is named after the file, so a file rename breaks Java binary compatibility.
DSL marker checks
- DSL markers with no-op targets:
@DslMarkerannotation targets on which the marker doesn't have any effect. They give a false sense of scope control. - DSL markers without explicit targets:
@DslMarkerannotations without an explicit@Target. The default target set has mostly targets on which the marker doesn't have any effect. - DSL markers on no-op type positions: DSL markers on type positions where they don't affect scope control.
Meaningful exemptions
- Exemptions without explanation:
@Intentionally*annotations with the defaultOTHERreason and a blank description. They don't explain anything. - Redundant exemptions:
@Intentionally*annotations on declarations their check doesn't report.