| # AGENTS.md — Guidelines for AI Coding Agents in KSP | |
| Welcome! This file defines the mandatory workflow, engineering methodology, and project context for AI coding agents working in the **Kotlin Symbol Processing (KSP)** repository. | |
| --- | |
| ## 1. Documentation Discovery & Reference Map | |
| 1. **Read `CONTRIBUTING.md` First**: Before proposing plans or modifying code, read `CONTRIBUTING.md`. It is the authoritative source for the bug contribution workflow (`@Bug` / `BugState`), `api/api.base` verification (`checkApi` / `updateApi`), and writing unit tests in `kotlin-analysis-api`. | |
| 2. **Consult Additional Documentation On-Demand**: Read the following repository documents when relevant to your task. Documentation can be found in Markdown files, LICENSE, and doc comments in Kotlin source files. | |
| --- | |
| ## 2. Core Engineering Methodology: Scientific Method & Zero Speculation | |
| You are working on a compiler plugin and symbol processing engine. **There must be zero speculation, hand-waving, or hallucination.** | |
| * **The Codebase is the Single Source of Truth**: Every claim, diagnosis, or proposed change must be backed by concrete code snippets and traced through the actual codebase. | |
| * **Falsify Hypotheses First (Scientific Method)**: | |
| * Whenever you form a hypothesis about how a symbol is resolved, how a type is computed, or why a bug occurs, **actively try to disprove your hypothesis first** using concrete code examples and dataflow examples from the codebase. | |
| * Trace the exact **dataflow** end-to-end (e.g., from `Resolver` entry points to `AnnotationResolutionStrategy` / Analysis API session calls to `KSNode` / `KSType` wrappers to PSI / FIR symbols) and cite the concrete classes, functions, and line ranges involved. | |
| * Revise your mental model repeatedly whenever the code contradicts your assumptions. | |
| * **No Guessing**: If an API contract, compiler behavior, or user requirement is ambiguous, inspect the implementation and test suite (`kotlin-analysis-api/testData` and `KSPUnitTestSuite.kt`) or ask the user clarifying questions rather than guessing. | |
| * **Outline a Detailed Plan First**: Always outline a clear, detailed plan supported by code references and dataflow analysis before you begin. Use this plan as your reference when you are making changes. | |
| * **Preserve & Synchronize Documentation**: | |
| * Preserve all existing comments and docstrings unrelated to your changes unless explicitly instructed otherwise. | |
| * **Keep Documentation in Sync with Code Changes**: Whenever you modify code, behavior, APIs, Gradle properties, or build configurations, you **must** also update the corresponding KDoc/doc comments and any relevant documentation files in the repository (e.g., `README.md`, `CONTRIBUTING.md`, `DEVELOPMENT.md`, `AGENTS.md`, or `docs/`) so that documentation never drifts out of sync with the implementation. This AGENTS.md file must also be kept in sync. | |
| --- | |
| ## 3. License & Legal Compliance | |
| * **License**: This repository is licensed under the **Apache License, Version 2.0** (see `LICENSE`). | |
| * **CLA**: Contributions require a Google Contributor License Agreement (`CONTRIBUTING.md`). | |
| * **Copyright Headers**: All new source files (`.kt`, `.java`) must include the standard Apache 2.0 license header used across the codebase: | |
| ```kotlin | |
| /* | |
| * Copyright <CURRENT YEAR> Google LLC | |
| * Copyright 2010-<CURRENT YEAR> JetBrains s.r.o. and Kotlin Programming Language contributors. | |
| * | |
| * Licensed under the Apache License, Version 2.0 (the "License"); | |
| * you may not use this file except in compliance with the License. | |
| * You may obtain a copy of the License at | |
| * | |
| * http://www.apache.org/licenses/LICENSE-2.0 | |
| * | |
| * Unless required by applicable law or agreed to in writing, software | |
| * distributed under the License is distributed on an "AS IS" BASIS, | |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| * See the License for the specific language governing permissions and | |
| * limitations under the License. | |
| */ | |
| ``` | |
| where `<CURRENT YEAR>` is the current year. | |
| You will likely find files that do not have a copyright header. The headers may have been lost when | |
| moving the file in the editor. Do not restore those. | |
| --- | |
| ## 4. Repository Architecture & Module Guide | |
| > **Important Note on KSP1**: KSP 1.x has been removed and is no longer supported (`README.md`). All active compiler engine development targets **KSP2** (`kotlin-analysis-api`). | |
| The project consists of Gradle subprojects configured in `settings.gradle.kts`: | |
| | Module | Purpose & Key Details | | |
| |:-----------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | |
| | `:api` | Public-facing, dependency-free library (`com.google.devtools.ksp:symbol-processing-api`). Tracked by Metalava against `api/api.base`. | | |
| | `:kotlin-analysis-api` | Core KSP2 engine implemented on top of the Kotlin Analysis API (FIR/K2). Key entry points: `KotlinSymbolProcessing.kt` (`src/main/kotlin/com/google/devtools/ksp/impl/`), `ResolverAAImpl.kt`, `AnnotationResolutionStrategy.kt` (`src/main/kotlin/com/google/devtools/ksp/common/impl/` with `AAResolutionStrategy` and `PsiResolutionStrategy`), all `KS*` symbol implementations (`src/main/kotlin/com/google/devtools/ksp/impl/symbol/`), and the primary unit test suite (`KSPUnitTestSuite.kt`). | | |
| | `:symbol-processing-aa-embeddable` | Repackages `:kotlin-analysis-api` and its dependencies into a self-contained uber-jar, relocating bundled packages under the `ksp.*` namespace (`symbol-processing-aa-embeddable/build.gradle.kts`) to avoid classpath conflicts. Entry point: `KSPLoader.loadAndRunKSP()`. | | |
| | `:gradle-plugin` | The KSP Gradle plugin (`id("com.google.devtools.ksp")`, `KspGradleSubplugin` in `KspSubplugin.kt`, and `KspAATask.kt`). Configures KSP tasks for JVM, Android, and Kotlin Multiplatform (KMP) projects. | | |
| | `:common-util` | Shared internal utilities used by `:kotlin-analysis-api` and other modules. | | |
| | `:common-deps` | Shared dependencies and command-line argument parsing utilities (`symbol-processing-common-deps`). Uses `:cmdline-parser-gen` via KSP. | | |
| | `:cmdline-parser-gen` | Internal KSP processor used during the build to generate command-line parser code for `:common-deps`. | | |
| | `:integration-tests` | End-to-end Gradle TestKit tests validating the published KSP uber-jar and Gradle plugin across real build scenarios (`primaryTest`, `secondaryTest`, `androidTest`, `agpTest`). | | |
| | `:symbol-processing` | Dummy POM-only artifact maintained for `KotlinCompilerPluginSupportPlugin` compatibility. | | |
| | `:test-utils` | Legacy test utilities. **Deprecated for new unit tests** (`CONTRIBUTING.md`)—all new unit tests belong in `:kotlin-analysis-api`. | | |
| --- | |
| ## 5. Contribution, Bug & Testing Workflows | |
| Read `CONTRIBUTING.md`. | |
| ## 6. Build, Version Synchronization & Verification Reference | |
| ### JDK & Kotlin Version Constraints | |
| * Carefully read the Gradle build files for a particular module to find out what its Java and Kotlin constraints are. | |
| * **Decoupled Versions (`gradle.properties` & `gradle/libs.versions.toml`)**: | |
| * `buildKotlinVersion` / `buildKspVersion`: Used in `gradle.properties` to bootstrap and compile the KSP project itself. | |
| * `kotlinBaseVersion` (`kotlin-base`) & `agpBaseVersion` (`agp-base`): **Duplicated in both `gradle.properties` and `gradle/libs.versions.toml`**. `gradle-plugin`'s `TestConfig` loads `gradle.properties` directly at test runtime—**always keep both files in sync**. | |
| * `aa-kotlin-base` (`aaKotlinBaseVersion`): The specific (often developmental) Kotlin version used for Analysis API dependencies in `:kotlin-analysis-api` and `:symbol-processing-aa-embeddable`. | |
| ### Essential Gradle Tasks | |
| * **Run a single unit test method across all 4 suite configurations**: | |
| > Note: Because `KSPUnitTestSuite` is `abstract`, use a wildcard or a concrete subclass name with `--tests`: | |
| ```bash | |
| ./gradlew :kotlin-analysis-api:test --tests "*.<testMethodName>" | |
| ``` | |
| * **Run all Analysis API unit tests**: | |
| ```bash | |
| ./gradlew :kotlin-analysis-api:test | |
| ``` | |
| * **Check / Update Public API Signatures (`Metalava`)**: | |
| Whenever modifying public declarations in `:api`, verify compatibility against `api/api.base`: | |
| ```bash | |
| ./gradlew :api:checkApi | |
| ./gradlew :api:updateApi | |
| ``` | |
| * **Shadow JAR & Relocation Validation**: | |
| * `./gradlew :kotlin-analysis-api:validateShadowJar`: Runs `jdeps` against `kotlin-analysis-api/shadow-validation-baseline.txt` and verifies no forbidden packages (such as `org/apache/log4j/jdbc`) leak into the shadow JAR. | |
| * `./gradlew :symbol-processing-aa-embeddable:shadowJar`: Verifies that all bundled classes are relocated into allowed `ksp.*` namespaces. | |
| * **Gradle Plugin Tests**: | |
| * `./gradlew :gradle-plugin:test`: Runs tests for the KSP Gradle plugin. | |
| * **Run Integration Tests**: | |
| Integration tests publish all artifacts to `<rootProject>/build/repos/test` and run Gradle TestKit suites (`integration-tests/build.gradle.kts`): | |
| ```bash | |
| ./gradlew :integration-tests:primaryTest | |
| ./gradlew :integration-tests:secondaryTest | |
| ./gradlew :integration-tests:androidTest | |
| ./gradlew :integration-tests:agpTest | |
| ``` | |
| Integration tests may take a long time to run so it may be helpful to just run a single test or test class when making changes, e.g., | |
| ```bash | |
| ./gradlew :integration-tests:primaryTest --tests "com.google.devtools.ksp.test.primary.<TestClass>.<method>" | |
| ``` | |
| where `TestClass` is the name of the class containing tests and `method` is the name of test method/entrypoint. | |
| * **Full Verification**: | |
| Before submitting a pull request to the KSP repository, you must always run the entire `./gradlew check` task and check that it completes successfully. | |
| > Note: It may be necessary to pass `--rerun-tasks` to ensure cached test or task outputs are re-evaluated after changes. | |
| ```bash | |
| ./gradlew check --rerun-tasks | |
| ``` |