Use the /code-doc-writer:code-doc-writer skill (https://mr3zee.github.io/code-doc-writer/) in every session.
A Kotlin K2 compiler plugin, a Gradle plugin, an exemption fixer, a report-aggregation plugin, and an
annotations library. The checkers warn library authors about public API declarations that are hard to
evolve. README.md lists the diagnostics. DOCS_GUIDELINE.md holds the rules for every text a person reads.
The compiler plugin and the fixer have no plain test task, only one task for each supported Kotlin version
(k240Test, k2410Test, ...). ./gradlew :<module>:tasks --all lists them.
./gradlew :library-api-watchdog-compiler-plugin:k2410Test # diagnostics tests against Kotlin 2.4.10
./gradlew :library-api-watchdog-compiler-plugin:latestKotlinTest # the daily CI run: tests against the newest Kotlin dev build only
./gradlew :library-api-watchdog-compiler-plugin:generateTests # regenerate JUnit classes from test data
./gradlew :library-api-watchdog-exempts-fixer:k2410Test # fixer tests plus the compiler-plugin integration test
./gradlew :gradle-plugin-test:allVersionedFunctionalTests # Gradle TestKit tests against every supported Kotlin version
./gradlew :gradle-plugin-test:k2410FunctionalTest # the same against one Kotlin version
./gradlew :gradle-plugin:test :gradle-plugin:library-api-watchdog-report-aggregation:test # unit tests of the included gradle-plugin build
./gradlew :library-api-watchdog-compiler-plugin:k2410Test --tests "*JvmDiagnosticTestGenerated*" # filter generated tests
./gradlew :library-api-watchdog-compiler-plugin:benchmarkCorpusAudit # check that the corpus triggers every benchmark-eligible checker
./gradlew :library-api-watchdog-compiler-plugin:benchmarkBaseline -Pbenchmark.baseline.allowMissing=true # the CI benchmark check, report only on a machine without a baselineEach file in compiler-plugin/src/commonTest/data/diagnostics/ and messages/ is one generated test method. Run
generateTests after you add, remove, or rename one. messages/ checks the rendered text of every diagnostic:
inline markers plus a .messages.txt dump of the full messages (JvmDiagnosticMessagesTestGenerated). The first
run generates a missing dump. The dump replaces the macOS shortcut ⌘N with Alt+Insert. Hand-written tests in
compiler-plugin/src/commonTest/kotlin run in every k*Test task.
Docs checks run in docs/ after npm ci. The docs-checks.yml workflow runs all four:
npm test # the remark plugins: diagnostic annotations in code samples, check-page links, README order
npm run check:diagnostic-exemptions # the exemption wording in the check pages matches diagnostics.json
npm run check:changelog # the website changelog matches CHANGELOG.md, `npm run sync:changelog` updates it
npm run build # the site build, fails on a broken link or anchor- The repository is a composite build, as in the dev kit's
compiler-plugin-template. The root build has the compiler plugin, the fixer, and the functional tests (:gradle-plugin-test).gradle-plugin(withreport-aggregation) andplugin-annotationsare included builds. Address their tasks with the build name first::gradle-plugin:test. The rootcheckand publication tasks also run in the included builds. - Every plugin and Maven dependency comes from the Space proxies of
gradle/repositories.settings.gradle.kts. Never add another Maven repository. A proxy takes a package from one upstream repository only, and the first request of a new version needs a token (CONTRIBUTING.md, "Build"). The workflows have it, a pull request from a fork doesn't. - GitHub Actions doesn't publish a release. The Maven Central and Gradle Plugin Portal publications run outside this
repository, between the
Pre-releaseandPost-publishworkflows. Space gets development versions only. RELEASE.md has the process. - The
artifacts/lists of the root build andplugin-annotationshold the published files of the Maven Central modules. After a change of a publication, run./gradlew dumpArtifactsand commit the lists. A change ofkotlinCliMinis such a change, because the lists of the compiler plugin and the fixer have that version in an artifact name (-k240). The Gradle plugin and the report aggregation plugin go to the Gradle Plugin Portal only, so they have no list, and the rootpublishAllPublicationsToBuildRepositorytask leaves them out. library.propertiesholdsgroupandversion, notgradle.properties, because an included build doesn't read the rootgradle.properties. Thedevkitsettings plugin inbuild-logic-settingssets both in every build. The dev kit version is thedevkitentry of the version catalog. The dailyDev kit updateworkflow updates it, not Renovate.versioninlibrary.propertiesis the next development version, not the latest release. The release build and the docs deploy get the release version fromLIBRARY_VERSION, so the README has no plugin version. Only a manual run ofdocs.ymlonmainwith theversioninput deploys the website. ThePost-publishworkflow starts it.- A pull request doesn't edit
CHANGELOG.md. ThePre-releaseworkflow writes the section of a release from the GitHub generated release notes, after the text of an optional## Unreleasedsection. - The
Dev kit update,Pre-release, andPost-publishworkflows push their branches and open their pull requests as the Watchdog bot, a GitHub App (CONTRIBUTING.md, "Watchdog bot"). A pull request ofGITHUB_TOKENstartspull_requestruns that wait for an approval. The test workflows skip thepull_requestruns ofWATCHDOG_BOT_LOGIN. The merges useGITHUB_TOKEN, so a merge of a bot pull request starts no workflow onmain. - The ruleset of
mainrequires one check,all_greenofpull-request-checks.yml(CONTRIBUTING.md, "Pull request checks"). A check workflow has nopull_requesttrigger, becausepull-request-checks.ymlcalls it. A called workflow can't have a job with a write permission, because a pull request from a fork then fails at the start. Sodocs.ymlhas the deploy job, anddocs-checks.ymlhas the checks. - A project of an included build depends on the root build's projects, and the reverse, by coordinates
(
"$group:<name>:$version"), never withproject(...). Composite substitution resolves them. diagnostics.jsonis the single source of truth for diagnostic texts. The build generatesWatchdogDiagnosticMessages(compiler plugin),WatchdogChecks(Gradle plugin and fixer),WatchdogCheckDescriptions(report aggregation), and theDiagnosticenum of the Gradle functional tests from it. The docs build fails on a diagnostic name that it doesn't list or a range that matches no sample line.DocsExamplesTestcompiles every docs sample and checks that the compiler reports exactly the annotated diagnostics, ranges, and parameters.- The Gradle functional tests describe a build with the DSL in
WatchdogProject.kt(jvmProject,kmpProject,androidLibrary,kmpAndroidProject). They check output with theBuildResultassertions inBuildAssertions.kt, and an assertion matches the first paragraph of a message. A new always-error diagnostic goes intoalwaysErrorDiagnostics. - The compiler plugin must not reference
com.intellijtypes in bytecode (a field type, a method signature, or a class literal). The jar runs in the CLI and in the relocatedkotlin-compiler-embeddableclasspath, and a reference links in one of them only.IntellijReferencesTestfails on each one. A type argument is fine, because erasure removes it. So a custom positioning strategy is impossible: itsmarkoverride never binds in the embeddable compiler, and the default strategy marks the whole declaration. A checker reports on a child source element fromKtSourceElement.childTokenofFirApiCompat.ktinstead. - The compiler plugin compiles against every Kotlin version from
kotlinCliMin(2.2.20).FirApiCompat.ktdeclares each API that differs between the versions as anexpect. Theactualdeclarations are in the source sets ofversionHierarchyincompiler-plugin/build.gradle.kts(pre2320DevMain,post24DevMain, ...). - An IDE build (
2.3.20-ij253-119) or a dev build of a version has only a part of the compiler API of the release.splitDevcompares the base version, so aDevsource set (post2320DevMain) has these builds.splitwith a condition puts the versions that match into thepresource set. Compile every target to find the side that an API needs. - A test handler goes into the step with
useHandlersAtFirst. Before Kotlin 2.3.0, the test framework doesn't run the handlers that followNoFirCompilationErrorsHandlerwhen the module has an error.RUN_PIPELINE_TILL: FRONTENDsuppresses that failure, so the test then passes without a check. - The fixer uses K2 PSI entry points only, with unrelocated
com.intellijimports, and compile-only dependencies. The Gradle task runs it in a separate JVM with thekotlin-compilerartifact of the project's Kotlin version. - The Gradle plugin checks the task graph in
gradle.taskGraph.whenReady, never on task realization, because IDE sync realizes every task. - Android compilations resolve dependencies through an
android-classes-jarartifact view, because a project AAR has no artifact without it. The plugin recognizes them by theandroidJVM environment of the compile classpath, because thecom.android.kotlin.multiplatform.librarytarget of AGP 8 reports platform typejvm. :library-api-watchdog-report-aggregationis a separate artifact, so a root project that applies it doesn't put the KGP-dependent support plugin on every project's plugin classpath.exemptExistingApiwrites the aggregate report through two project-local hooks, because project isolation forbids a finalizer on another project's task.generateApiWatchdogReportbuilds the report artifact. When the task graph has theexemptExistingApiof the project,generateApiWatchdogReportskips itself, and the report ofexemptExistingApistays. The aggregation plugin finalizes the root'sexemptExistingApi(its own lifecycle task when the root has no Watchdog) withaggregateApiWatchdogReports.- The benchmark baseline (
compiler-plugin/src/benchmark/baseline/) is valid for one machine profile. Record it with theBenchmark baselineworkflow (recordinput), never on a developer machine. The check comparesbytesonly. plugin-annotationsapplies the Kotlin Gradle plugin ofkotlinCliMin, so its ABI tasks have the namescheckLegacyAbiandupdateLegacyAbi, notcheckKotlinAbiandupdateKotlinAbi.library-api-watchdog.jvm-target-conventionssets the bytecode level of a published module. The annotations target Java 8. The Gradle plugin and the report aggregation target Java 17, because the dev kit'sgradle-plugin-runtimeis a Java 17 library. The compiler plugin and the fixer don't apply the convention. The dev kit compiles their versioned classes for Java 8 itself.- The Android functional tests skip themselves without an Android SDK. AGP 8 fixtures run with the Gradle version
pinned in
AgpVersion.AGP8ofWatchdogProject.kt, because AGP 8 can't run on Gradle 9.6 or later. The dev kit skips every multiplatform fixture on Kotlin versions older than the Kotlin version that compiled the annotations klibs, because KLIBs aren't forward compatible.
- The entry in
diagnostics.json. - The factory in
WatchdogDiagnostics, a checker infir/, and its registration inWatchdogFirCheckers. - The severity property and name mapping in
WatchdogGradleExtension, and a specimen in theunacknowledgedFileofWatchdogProjectTest. - The checker list and the severity sample in README.md.
- Test data in
diagnostics/, amessages/file that triggers everyparameterValuesvariant, and the regenerated tests. - The fixer:
ExemptionRegistry, the expected-names set inFixerProtocolTest, and the specimen file ofExemptExistingApiTest. - The docs: the check page at the
docspath fromdiagnostics.json,docs/sidebars.ts, and the check list indocs/pages/overview.md. - The benchmarks in
compiler-plugin/src/benchmark/, only when the checker can report a warning. Add aCheckerSubject, the@Paramlists of both benchmark classes, and a triggering shape inBenchmarkCorpus. Then runbenchmarkCorpusAudit.