Skip to content

Latest commit

 

History

History
149 lines (137 loc) · 12.5 KB

CLAUDE.md

File metadata and controls

149 lines (137 loc) · 12.5 KB

CLAUDE.md

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.

Commands

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 baseline

Each 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

Constraints the code doesn't show

  • 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 (with report-aggregation) and plugin-annotations are included builds. Address their tasks with the build name first: :gradle-plugin:test. The root check and 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-release and Post-publish workflows. Space gets development versions only. RELEASE.md has the process.
  • The artifacts/ lists of the root build and plugin-annotations hold the published files of the Maven Central modules. After a change of a publication, run ./gradlew dumpArtifacts and commit the lists. A change of kotlinCliMin is 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 root publishAllPublicationsToBuildRepository task leaves them out.
  • library.properties holds group and version, not gradle.properties, because an included build doesn't read the root gradle.properties. The devkit settings plugin in build-logic-settings sets both in every build. The dev kit version is the devkit entry of the version catalog. The daily Dev kit update workflow updates it, not Renovate.
  • version in library.properties is the next development version, not the latest release. The release build and the docs deploy get the release version from LIBRARY_VERSION, so the README has no plugin version. Only a manual run of docs.yml on main with the version input deploys the website. The Post-publish workflow starts it.
  • A pull request doesn't edit CHANGELOG.md. The Pre-release workflow writes the section of a release from the GitHub generated release notes, after the text of an optional ## Unreleased section.
  • The Dev kit update, Pre-release, and Post-publish workflows push their branches and open their pull requests as the Watchdog bot, a GitHub App (CONTRIBUTING.md, "Watchdog bot"). A pull request of GITHUB_TOKEN starts pull_request runs that wait for an approval. The test workflows skip the pull_request runs of WATCHDOG_BOT_LOGIN. The merges use GITHUB_TOKEN, so a merge of a bot pull request starts no workflow on main.
  • The ruleset of main requires one check, all_green of pull-request-checks.yml (CONTRIBUTING.md, "Pull request checks"). A check workflow has no pull_request trigger, because pull-request-checks.yml calls 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. So docs.yml has the deploy job, and docs-checks.yml has the checks.
  • A project of an included build depends on the root build's projects, and the reverse, by coordinates ("$group:<name>:$version"), never with project(...). Composite substitution resolves them.
  • diagnostics.json is the single source of truth for diagnostic texts. The build generates WatchdogDiagnosticMessages (compiler plugin), WatchdogChecks (Gradle plugin and fixer), WatchdogCheckDescriptions (report aggregation), and the Diagnostic enum 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. DocsExamplesTest compiles 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 the BuildResult assertions in BuildAssertions.kt, and an assertion matches the first paragraph of a message. A new always-error diagnostic goes into alwaysErrorDiagnostics.
  • The compiler plugin must not reference com.intellij types in bytecode (a field type, a method signature, or a class literal). The jar runs in the CLI and in the relocated kotlin-compiler-embeddable classpath, and a reference links in one of them only. IntellijReferencesTest fails on each one. A type argument is fine, because erasure removes it. So a custom positioning strategy is impossible: its mark override never binds in the embeddable compiler, and the default strategy marks the whole declaration. A checker reports on a child source element from KtSourceElement.childToken of FirApiCompat.kt instead.
  • The compiler plugin compiles against every Kotlin version from kotlinCliMin (2.2.20). FirApiCompat.kt declares each API that differs between the versions as an expect. The actual declarations are in the source sets of versionHierarchy in compiler-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. splitDev compares the base version, so a Dev source set (post2320DevMain) has these builds. split with a condition puts the versions that match into the pre source 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 follow NoFirCompilationErrorsHandler when the module has an error. RUN_PIPELINE_TILL: FRONTEND suppresses that failure, so the test then passes without a check.
  • The fixer uses K2 PSI entry points only, with unrelocated com.intellij imports, and compile-only dependencies. The Gradle task runs it in a separate JVM with the kotlin-compiler artifact 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-jar artifact view, because a project AAR has no artifact without it. The plugin recognizes them by the android JVM environment of the compile classpath, because the com.android.kotlin.multiplatform.library target of AGP 8 reports platform type jvm.
  • :library-api-watchdog-report-aggregation is a separate artifact, so a root project that applies it doesn't put the KGP-dependent support plugin on every project's plugin classpath.
  • exemptExistingApi writes the aggregate report through two project-local hooks, because project isolation forbids a finalizer on another project's task. generateApiWatchdogReport builds the report artifact. When the task graph has the exemptExistingApi of the project, generateApiWatchdogReport skips itself, and the report of exemptExistingApi stays. The aggregation plugin finalizes the root's exemptExistingApi (its own lifecycle task when the root has no Watchdog) with aggregateApiWatchdogReports.
  • The benchmark baseline (compiler-plugin/src/benchmark/baseline/) is valid for one machine profile. Record it with the Benchmark baseline workflow (record input), never on a developer machine. The check compares bytes only.
  • plugin-annotations applies the Kotlin Gradle plugin of kotlinCliMin, so its ABI tasks have the names checkLegacyAbi and updateLegacyAbi, not checkKotlinAbi and updateKotlinAbi.
  • library-api-watchdog.jvm-target-conventions sets 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's gradle-plugin-runtime is 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.AGP8 of WatchdogProject.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.

Adding a new diagnostic

  1. The entry in diagnostics.json.
  2. The factory in WatchdogDiagnostics, a checker in fir/, and its registration in WatchdogFirCheckers.
  3. The severity property and name mapping in WatchdogGradleExtension, and a specimen in the unacknowledgedFile of WatchdogProjectTest.
  4. The checker list and the severity sample in README.md.
  5. Test data in diagnostics/, a messages/ file that triggers every parameterValues variant, and the regenerated tests.
  6. The fixer: ExemptionRegistry, the expected-names set in FixerProtocolTest, and the specimen file of ExemptExistingApiTest.
  7. The docs: the check page at the docs path from diagnostics.json, docs/sidebars.ts, and the check list in docs/pages/overview.md.
  8. The benchmarks in compiler-plugin/src/benchmark/, only when the checker can report a warning. Add a CheckerSubject, the @Param lists of both benchmark classes, and a triggering shape in BenchmarkCorpus. Then run benchmarkCorpusAudit.