detekt rules in your app

What detekt checks in the project, where it runs, the project's own rules, how a finding is dealt with, and how an app that uses Pantrix UI turns these rules on.

1. What is Detekt?

Detekt is a static code analysis tool for Kotlin. Kotlinter looks at how code looks; detekt looks at what code does and how it is built: a function that is too complex, code that is not needed, a place where a rule is broken. Two kinds of rules run in this project:

• detekt's own rules: complexity, naming, likely bugs, style.

• The project's own rule set, PantrixUIRule: in the module tooling/detekt-rules. The machine's form of the library's rules in CONTRIBUTING.md, and of the rules of accessibility, language and tokens.

2. Where does it run?

Of detekt's own rules, UndocumentedPublicClass, UndocumentedPublicFunction and UndocumentedPublicProperty are on in the library: no class, function or property is left without KDoc. An enum's entry counts as a property too. Parameters are held by the project's UndocumentedParameter (section 3).

The setup is in two plugins of build-logic: DetektSetupPlugin, which pantrix.codequality applies, for the library, and pantrix.demo.detekt for the demo. Tests are outside the project's rules.

Running it:

• ./gradlew detekt: in every module, runs each target's own task. In Kotlin Multiplatform the analysis is made target by target (detektMetadataCommonMain, detektJvmMain, detektAndroidMain, detektIosArm64Main…); the plain detekt task is wired to all of them, or it would pass green without looking at anything.

• ./gradlew :ui:components:detekt: in a single module.

• After the rules change (tooling/detekt-rules): ./gradlew detekt --no-daemon. A daemon that is running keeps using the old rule classes. ./gradlew --stop is not used: it stops the IDE's daemon too.

The reports are in each module's build/reports/detekt/ folder: HTML (for reading) and SARIF (for tools).

3. The project's rules

Where the rules can be configured (allowedPathPattern, includes, excludes, lists of names) is written in each rule's KDoc.

4. Dealing with a finding

A finding is closed in one of two ways:

• It is fixed. This is the answer to most findings.

• It is suppressed where it stands, with its reason. Where a rule is broken on purpose, the suppression goes in the narrowest place (a constant, a small function) and its reason is written on the same line:

@Suppress("FixedSideLayout") // A JSON document is laid out from the left in every language.
private val COPY_CORNER: Alignment = AbsoluteAlignment.TopRight

No baseline is used. A baseline file puts the finding where nobody looks; while the finding is there, the rule seems to be kept.

5. Pantrix's rules in your own app

The rules are published as com.pantrixui:detekt-rules. An app gives them to detekt as a plugin:

dependencies {
    detektPlugins("com.pantrixui:detekt-rules:0.1.0-alpha03")
}

Where detekt is built upon its own default configuration (buildUponDefaultConfig = true), the rule set's own configuration turns three rules on: FixedSideLayout, ImageWithoutDescription, UntaggedControl. The rules of the library alone start off; an app turns them on in its own configuration if it wants to. The recommended configuration, with the last two reporting and not stopping the build:

build:
  weights:
    UntaggedControl: 0
    ImageWithoutDescription: 0

PantrixUIRule:
  # If the app uses no Material:
  NoMaterialImport:
    active: true

The rule classes are compiled for JVM 17: the JDK that runs detekt has to be 17 or newer.

6. Detekt and Kotlinter