ADFA-4823: Kotlin go-to-definition in the K2 LSP (#1597)

Author: itsaky-adfa

build.gradle.kts

@@ -67,6 +67,16 @@ buildscript {
 	}
 }
 
+// `jacocoAggregateReport` dependsOn every subproject's `testV8DebugUnitTest` and `sonarqube`
+// dependsOn that, so a hard test failure skips both - even under `--continue` - and the analysis
+// run uploads an empty coverage artifact with no Sonar analysis at all. That, not any individual
+// module's broken suite, is the only reason `ignoreFailures` exists here: keep test failures
+// non-fatal when the analysis chain is what was asked for, and let every ordinary build gate on them.
+val analysisRun =
+	gradle.startParameter.taskNames.any {
+		it.substringAfterLast(':') in setOf("sonar", "sonarqube", "jacocoAggregateReport")
+	}
+
 subprojects {
 	plugins.apply("jacoco")
 
@@ -78,14 +88,28 @@ subprojects {
 	FDroidConfig.load(project)
 
 	tasks.withType<Test> {
-		// Continue even if tests fail, so coverage data is written
-		ignoreFailures = true
+		ignoreFailures = analysisRun
+
+		// Gradle's default test-worker heap is 512m, too small for the Robolectric +
+		// Kotlin Analysis API suites (:lsp:kotlin peaks near 240m and keeps growing).
+		// Keep it explicit so the suites fail on a real regression, not on the default.
+		maxHeapSize = "1g"
 
 		// Backstop: kill any individual Test task that runs longer than 10 minutes.
 		// Prevents a single hung test JVM (e.g. the Tooling API child) from burning
 		// the entire CI job budget.
 		timeout.set(Duration.ofMinutes(10))
 
+		// A test worker's default working dir is the module directory, so an unpathed
+		// -XX:+HeapDumpOnOutOfMemoryError drops a heap dump of up to maxHeapSize into the source
+		// tree, untracked and not gitignored. Keep dumps under build/ instead, one per task.
+		val heapDumpFile =
+			layout.buildDirectory
+				.file("test-heapdumps/$name.hprof")
+				.get()
+				.asFile
+		doFirst { heapDumpFile.parentFile.mkdirs() }
+
 		// JPMS opens required by the unit-test stack on JDK 17+:
 		//   - jdk.unsupported/sun.misc: HiddenApiBypass.<clinit> reflectively
 		//     resolves sun.misc.Unsafe; without this the IDEApplication
@@ -105,6 +129,14 @@ subprojects {
 			"--add-opens=java.base/java.util=ALL-UNNAMED",
 			"--add-opens=java.base/java.util.concurrent=ALL-UNNAMED",
 			"--add-opens=jdk.unsupported/sun.misc=ALL-UNNAMED",
+			// An OutOfMemoryError inside a test deadlocks Gradle's TestWorker: the
+			// OOM unwinds the runQueue.take() loop, whose finally needs the TestWorker
+			// monitor that the in-flight stop() already holds while blocked on
+			// runQueue.put() (capacity 1). The worker then never exits and the build
+			// hangs. Exiting on the first OOM turns that hang into a task failure.
+			"-XX:+ExitOnOutOfMemoryError",
+			"-XX:+HeapDumpOnOutOfMemoryError",
+			"-XX:HeapDumpPath=${heapDumpFile.absolutePath}",
 		)
 
 		// Attach jacoco agent

docs/adr/0010-navigation-resolves-via-analysis-api.md

@@ -0,0 +1,46 @@
+# 0010. Kotlin navigation resolves via the Analysis API, not the symbol index
+
+- **Status:** Proposed
+- **Date:** 2026-07-27
+- **Deciders:** Code On The Go team
+
+## Context
+
+The K2 Kotlin LSP carries a substantial symbol-indexing stack: `JvmSymbolIndex` over library jars, `KtFileMetadataIndex` over source files, and `KtSymbolIndex` tying them together, all SQLite-backed and refreshed by background workers. Completion and add-import lean on it heavily, and it is the cheap way to answer "what symbols named X exist in this workspace".
+
+Navigation features - go-to-definition (ADFA-4823) and find usages (ADFA-4824) - look superficially similar: given a name, find where it lives. A reader who has just read the completion code will reasonably expect navigation to query the same index.
+
+It cannot. The index stores names, kinds, visibility, and containing-class metadata, but **no source offsets** - `JvmSymbol`/`JvmSymbolInfo` have nowhere to put a declaration's position, and `KtFileMetadata` records only a file path plus its symbol keys. An index hit narrows the answer to a file at best; something still has to parse that file to find where in it the declaration sits. Worse, the index answers by *name*, while navigation must answer by *resolution* - which of the seven overloads of `foo`, through this module's dependency graph and content scopes, does this call site actually bind to.
+
+## Decision
+
+**Kotlin navigation resolves through the Analysis API and PSI only. The symbol indexes are not consulted.**
+
+- Given a caret offset, find the reference, then `analyze(ktFile) { reference.mainReference.resolveToSymbols() }`, falling back to `resolveToCall()` for convention references (`a + b`, `a[i]`, `by lazy`, destructuring, `for` loops) that have no name reference to resolve.
+- Convert each resolved symbol to its PSI declaration, and the declaration to a file plus a name-identifier range.
+- Correctness of scoping - module dependencies, content scopes, visibility - is delegated to the analysis session rather than reimplemented over index rows.
+
+## Consequences
+
+**Positive**
+
+- Results are *resolved*, not name-matched: the right overload, the right receiver, the right module.
+- Module dependency graphs and content scopes are respected by construction. No second, divergent notion of "which module can see what" to keep in sync with `ProjectStructureProvider`.
+- One code path for all three resolution scopes (same-file, inter-file, inter-module), so the test matrix covers behaviour rather than plumbing.
+
+**Negative / costs**
+
+- **Navigation requires a live analysis session.** Before one exists, go-to-definition returns nothing; it cannot degrade to an index-only answer. The user-facing gap - no way to say "still indexing" rather than "not found" - is cross-cutting across every LSP feature and remains unsolved.
+- Resolving a cross-module target means building PSI for the target file, which is more work than an index row lookup. Acceptable for a user-initiated, cancellable, one-at-a-time request; it would not be acceptable for a per-keystroke feature.
+- Symbols with no source PSI - stdlib, framework, any library jar - are simply unreachable. Library navigation would need decompilation or source-jar extraction, neither of which exists in the tree.
+
+## Alternatives considered
+
+- **Index-first, analysis fallback** - rejected: the index has no declaration offsets, so it can only narrow to a file and a second pass must parse it anyway. Extra machinery, no saved work, and a name-matched shortlist that can disagree with what the call site actually binds to.
+- **Index-only for cross-module targets** - rejected: two divergent code paths for the same user action, and cross-module results would be position-less, so they could not be selected in the editor.
+- **Extend the index to store declaration offsets** - rejected for now: offsets go stale on every edit, so the index would need write-through invalidation on document change to stay trustworthy for navigation, and it still would not answer overload resolution. Revisit only if navigation latency becomes a measured problem.
+
+## Related
+
+- [docs/features/kotlin-goto-definition.md](../features/kotlin-goto-definition.md) - the first feature built on this decision
+- [ADR 0001](0001-prefer-room-for-persistence.md) - persistence choices for the indexes this ADR declines to use

docs/adr/README.md

@@ -23,3 +23,4 @@ Format is lightweight **MADR / Nygard**: Context → Decision → Consequences 
 | [0007](0007-strictmode-whitelist-engine.md) | Enforce StrictMode via a custom whitelist engine | Proposed |
 | [0008](0008-retain-androidide-namespace.md) | Retain the `com.itsaky.androidide` namespace after rebrand | Proposed |
 | [0009](0009-jetpack-compose-for-new-ui.md) | Build new UI in Jetpack Compose, not XML Views | Proposed |
+| [0010](0010-navigation-resolves-via-analysis-api.md) | Kotlin navigation resolves via the Analysis API, not the symbol index | Proposed |