AGENTS.md

1# Analysis API Guidelines
2 
3A library for analyzing Kotlin code at the semantic level, providing structured access to symbols, types, and semantic relationships.
4 
5**Entry point:** Use [`analyze()`](analysis-api/src/org/jetbrains/kotlin/analysis/api/analyze.kt) to start an analysis session. See [Analysis API documentation](https://kotl.in/analysis-api) for a usage guide.
6 
7## Architecture
8 
9- **Platform** — Provides declarations, project structure, and modification events (IntelliJ, Standalone)
10- **Engine** — Performs code analysis using platform-provided information (K1, K2)
11- **User** — Code that calls `analyze()` to work with symbols and types
12 
13→ READ [`analysis-api-platform-interface/README.md`](analysis-api-platform-interface/README.md) for detailed architecture overview
14 
15## Relationship with PSI
16 
17Analysis API builds on top of Kotlin PSI (`compiler/psi/`):
18- **PSI** provides syntax (structure of code): `KtElement`, `KtExpression`, `KtDeclaration`
19- **Analysis API** provides semantics (meaning of code): `KaSymbol`, `KaType`
20 
21```
22PSI (syntax) → Analysis API (semantics) → Symbols, Types, Resolution
23```
24 
25**Both PSI and Analysis API follow shared development principles** documented in [`docs/contribution-guide/api-development.md`](docs/contribution-guide/api-development.md).
26 
27WHEN working with PSI elements:
28→ READ [`compiler/psi/AGENTS.md`](../compiler/psi/AGENTS.md) for PSI-specific rules and conventions
29 
30## Key Conventions
31 
32- `Ka` prefix for Analysis API types, `Kt` for PSI types
33- Prefer interfaces to classes for better binary compatibility
34- Properties for attributes, functions for actions with parameters
35- Return nullable types for operations that can fail (avoid exceptions for non-exceptional cases)
36- All implementations must validate lifetime ownership with `withValidityAssertion`
37- Mark experimental APIs with `@KaExperimentalApi`, implementation details with `@KaImplementationDetail`
38 
39## Working with Test Data
40 
41When modifying test data files or running generated tests (`*Generated`) that compare output against `.txt` files, use `updateTestData` (to rewrite files) or `checkTestData` (to verify only) instead of standard test commands. Both take their options as `-P` properties, so changing filters between runs stays fast.
42 
43### `updateTestData` — the only recommended way to update test data
44 
45```bash
46# Update test data by directory (preferred for iteration)
47./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/
48 
49# Update test data by test class pattern
50./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testClassPattern=.*ResolveTest.*
51 
52# Run only golden tests (useful for quick baseline updates)
53./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.goldenOnly=true
54 
55# Incremental update — only re-run variant tests for changed paths
56./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.incremental=true
57 
58# Limit to a subset of modules using task paths (Gradle task-name matching)
59./gradlew :analysis:analysis-api-fir:updateTestData :analysis:stubs:updateTestData
60```
61 
62`updateTestData` is fixed to update mode. There is no `updateTestDataGlobally` — Gradle's task-name matching runs the task in every applicable subproject when invoked from the repo root.
63 
64### `checkTestData` — verification only
65 
66If you specifically need to verify that existing test data is consistent without modifying anything (e.g., sanity-checking generated files after an `updateTestData` run), use `checkTestData`. It is the exact `-P`-driven counterpart of `updateTestData` but fixed to check mode: it fails on any mismatch and writes nothing.
67 
68```bash
69./gradlew checkTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/singleByPsi/
70```
71 
72Use this only for verification. For any workflow that writes test data, use `updateTestData`.
73 
74**Why use these tasks instead of plain `:test`?**
75- Run only relevant tests (filtered by path or class pattern)
76- Handle variant chains correctly (golden `.txt` files run before variant-specific `.js.txt`, `.wasm.txt`, etc.)
77- Automatically discover all modules that use managed test data
78- Detect and remove redundant variant files
79 
80For full options, see [test-data-manager-convention](../repo/gradle-build-conventions/test-data-manager-convention/README.md).
81 
82## Key Components
83 
84- [`analysis-api/`](analysis-api) - User-facing API surface (`KaSession`, `KaSymbol`, `KaType`)
85- [`analysis-api-platform-interface/`](analysis-api-platform-interface) - Platform abstraction (declaration providers, project structure, lifetime)
86- [`analysis-api-standalone/`](analysis-api-standalone) - CLI-based implementation of the Analysis API
87- [`analysis-api-fir/`](analysis-api-fir) - K2 implementation based on FIR
88- [`analysis-api-impl-base/`](analysis-api-impl-base) - Shared implementation utilities
89- [`low-level-api-fir/`](low-level-api-fir) - K2-specific infrastructure for lazy/incremental analysis
90- [`symbol-light-classes/`](symbol-light-classes) - Java PSI view of Kotlin declarations for interop
91- [`decompiled/light-classes-for-decompiled`](decompiled/light-classes-for-decompiled) - Light classes for decompiled/library code
92- [`test-data-manager/`](test-data-manager) - Infrastructure for managing test data files with variant chains
93 
94## Detailed Documentation
95 
96WHEN adding or modifying API endpoints:
97→ READ [`docs/contribution-guide/api-development.md`](docs/contribution-guide/api-development.md)
98 
99WHEN deprecating API or understanding stability categories:
100→ READ [`docs/contribution-guide/api-evolution.md`](docs/contribution-guide/api-evolution.md)
101 
102WHEN implementing platform components:
103→ READ [`analysis-api-platform-interface/README.md`](analysis-api-platform-interface/README.md)
104 
105WHEN working with light classes:
106→ READ [`symbol-light-classes/README.md`](symbol-light-classes/README.md)
107 
108WHEN working with lazy resolution (LL API):
109→ READ [`low-level-api-fir/README.md`](low-level-api-fir/README.md)
110 
111WHEN writing or managing test data files:
112→ READ [`test-data-manager/AGENTS.md`](test-data-manager/AGENTS.md)
113 
114WHEN seeking historical context on design decisions:
115→ READ [`docs/design-documents/README.md`](docs/design-documents/README.md) (these are historical snapshots, not necessarily up to date)
116 
117WHEN working with stubs:
118→ READ [`stubs/README.md`](stubs/README.md)
119