Skip to content

KaDiagnostics

@SubclassOptInRequired(markerClass = [KaImplementationDetail::class])
interface KaDiagnostics : KaLifetimeOwner, Sequence<KaDiagnosticWithPsi<*>>

A description of a diagnostic query, which yields the requested diagnostics on iteration.

KaDiagnostics is obtained from diagnostics. By default, the query yields diagnostics of common checkers which are not suppressed at their use site recursively – in other words, exactly the diagnostics which the compiler reports:

for (diagnostic in file.diagnostics()) {
    handle(diagnostic)
}

The default can be adjusted before the iteration begins:

file.diagnostics()
    .withCheckers(KaDiagnosticCheckerKind.COMMON, KaDiagnosticCheckerKind.EXTENDED)
    .ignoreSuppressed(true)
    .directOnly(true)
    .forEach { handle(it) }

Laziness

KaDiagnostics is a Sequence:

  • Calling diagnostics() itself doesn't trigger code analysis. The operation is intermediate and stateless.

  • Diagnostics are computed on-demand as the sequence is iterated over.

  • You can iterate over the same sequence multiple times.

See also

Properties

token

abstract val token: KaLifetimeToken

The KaLifetimeToken which determines the lifetime of the lifetime owner.

Functions

assertIsValidAndAccessible

directOnly

abstract fun directOnly(direct: Boolean): KaDiagnostics

Returns a KaDiagnostics which yields diagnostics only on the given KtElement itself depending on direct flag.

If direct is true, KaDiagnosticWithPsi of the element's children are not included, so the result is not the complete set of diagnostics which concern the element: a diagnostic about the element might be reported on one of its children, or on a containing element. Prefer false unless the diagnostics of the exact element are required.

The default behavior is false.

ignoreSuppressed

abstract fun ignoreSuppressed(ignore: Boolean): KaDiagnostics

Returns a KaDiagnostics which yields suppressed diagnostics depending on the value of ignore.

Suppressed diagnostics are not reported by the compiler, so they should not be presented to the user as is. They are useful for tooling which analyzes suppressions themselves, such as an inspection which detects redundant @Suppress annotations.

Collecting suppressed diagnostics does not require additional analysis.

The default behavior is true.

isValid

Whether the lifetime owner is still valid, i.e. we are still in the scope of the lifetime owner's regular lifetime.

iterator

abstract operator fun iterator(): Iterator<KaDiagnosticWithPsi<*>>

withCheckers

Returns a KaDiagnostics which yields diagnostics of the given checker kinds.

The kinds replace the currently requested kinds, they are not added to them. An empty kinds set results in no diagnostics, and no checkers are run in that case.

abstract fun withCheckers(vararg kinds: KaDiagnosticCheckerKind): KaDiagnostics

Returns a KaDiagnostics which yields diagnostics of the given checker kinds.

The kinds replace the currently requested kinds, they are not added to them. Passing no kinds results in no diagnostics, and no checkers are run in that case.

withValidityAssertion

inline fun <R> KaLifetimeOwner.withValidityAssertion(action: () -> R): R

Executes action only if the KaLifetimeOwner is still valid and accessible. Otherwise, throws a validity exception based on the concrete violation.