以下为本文档的中文说明analysis-api-extend-ka-resolver 是 JetBrains 平台中用于扩展 Kotlin 分析 API 解析器能力的技能。该技能的核心功能是为指定的 Kt* PSI(程序结构接口)类型添加 resolveSymbol() 和可选的 resolveCall() 方法支持,通过遵循已有解析器支持提交中建立的标准模式来实现。工作过程分为多个阶段:第一阶段是信息收集,首先在 compiler/psi/ 目录中搜索 PSI 类型的源文件(.java 或 .kt),读取文件以理解类层次结构,检查该类型是否已经实现了 KtResolvable 或 KtResolvableCall 接口;然后检查 KaResolver.kt 文件中是否已存在对该 PSI 类型的支持。使用场景包括:当 JetBrains 平台的 Kotlin 分析引擎需要为新的 PSI 类型添加符号解析和调用解析能力时;在开发 Kotlin 编译器插件或分析工具时需要扩展解析能力时。核心原则是严格遵循现有代码库中已建立的模式,不创造新的解析机制,而是扩展现有的 KaResolver 框架。该技能要求使用者对 Kotlin 编译器的 PSI 系统有深入理解,特别是 KtResolvable 和 KtResolvableCall 接口的语义和实现模式。通过系统化地按照已有提交的模式进行扩展,确保新增的解析支持与现有代码保持一致的风格和质量标准。Add KaResolver support for a PSI typeThis skill addsresolveSymbol()and optionallyresolveCall()support for a givenKt*PSI typeby following the established pattern from existing resolver support commits.The argument is the PSI type name, e.g.KtDestructuringDeclarationEntry.Phase 1: Gather informationFind the PSI type source file.Searchcompiler/psi/forKtPsiType.javaorKtPsiType.kt.Read the file to understand the class hierarchy and whether it already implementsKtResolvableorKtResolvableCall.Check KaResolver for existing support.Readanalysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KaResolver.ktand search for the PSI type. If it already hasresolveSymbol()/resolveCall()methods, inform the user and stop.Check for existing test data.Searchanalysis/analysis-api/testData/components/resolver/for test filesmentioning the PSI type or related scenarios.Read the Analysis API AGENTS.mdatanalysis/AGENTS.mdfor area-specific guidelines.Phase 2: Ask user questionsUseAskUserQuestionto ask these questions (all in one call):Question 1: Resolution kindHeader:“Resolution”Question:“ShouldKtPsiTypesupport symbol-only resolution (KtResolvable) or both symbol and call resolution (KtResolvableCall)?”KtResolvable— symbol resolution only (resolveSymbol())KtResolvableCall— both symbol and call resolution (resolveSymbol()resolveCall())Question 2: Symbol return typeHeader:“Symbol type”Question:“What shouldresolveSymbol()return forKtPsiType?”KaConstructorSymbolKaFunctionSymbolKaNamedFunctionSymbolKaCallableSymbol(Allow “Other” for types likeKaDeclarationSymbol, etc.)Question 3: Call return type (only ifKtResolvableCall)Header:“Call type”Question:“What shouldresolveCall()return forKtPsiType?”KaFunctionCallKaConstructorSymbolKaDelegatedConstructorCallKaAnnotationCallKaFunctionCallKaNamedFunctionSymbol(Allow “Other” for types likeKaSingleCall*, *,KaFunctionCall*, etc.)Phase 3: Execute changesUse the answers from Phase 2 to determine:RESOLUTION_KIND(KtResolvableorKtResolvableCall),SYMBOL_TYPE(e.g.KaCallableSymbol), andCALL_TYPE(e.g.KaSingleCall*, *).Step 1: PSI type — add interface implementationFile:The PSI source file found in Phase 1 (undercompiler/psi/).If the PSI type does NOT already implementKtResolvable/KtResolvableCall, add it:ForKtResolvable: addimplements KtResolvable(Java) or: KtResolvable(Kotlin)ForKtResolvableCall: addimplements KtResolvableCall(Java) or: KtResolvableCall(Kotlin)KtResolvableCallextendsKtResolvable, so only one is needed.Add the necessary import (org.jetbrains.kotlin.resolution.KtResolvableororg.jetbrains.kotlin.resolution.KtResolvableCall).Step 2: KaResolver interface — add methodsFile:analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KaResolver.kt2a: AddresolveSymbol()interface methodInsertafterthe last existing typedresolveSymbol()method (currentlyKtDestructuringDeclarationEntry.resolveSymbol())andbeforetryResolveCall().Follow the exact KDoc pattern — copy from a similar existing method and adapt:/** * Resolves the description by the given [KtPsiType]. * * #### Example * * kotlin * code example with // ^^^^ markers * * * Calling resolveSymbol() on a [KtPsiType] ... returns the [SYMBOL_TYPE] ... * if resolution succeeds; otherwise, it returns null (e.g., when unresolved or ambiguous). * * This is a specialized counterpart of [KtResolvable.resolveSymbol] focused specifically on description * * see tryResolveSymbols * see KtResolvable.resolveSymbol */KaExperimentalApipublicfunKtPsiTy pe.resolveSymbol():SYMBOL_TYPE?2b: AddresolveCall()interface method (only ifKtResolvableCall)Insertafterthe last existing typedresolveCall()method (currentlyKtDestructuringDeclarationEntry.resolveCall())andbeforecollectCallCandidates()./** * Resolves the given [KtPsiType] to a call description. * * #### Example * * kotlin * code example with // ^^^^ markers * * * Returns the corresponding [CALL_TYPE short name] if resolution succeeds; otherwise, it returns null * (e.g., when unresolved or ambiguous). * * This is a specialized counterpart of [KtResolvableCall.resolveCall] focused specifically on description * * see tryResolveCall * see KtResolvableCall.resolveCall */KaExperimentalApipublicfunKtPsiType.resolveCall():CALL_TYPE?2c: AddresolveSymbol()bridge functionInsertafterthe last existingresolveSymbolbridge (currentlyKtDestructuringDeclarationEntry.resolveSymbolbridge)andbeforethetryResolveCallbridge./** * Same KDoc as the interface method */// Auto-generated bridge. DO NOT EDIT MANUALLY!KaExperimentalApiKaContextParameterApicontext(session:KaSession)publicfunKtPsiType.resolveSymbol():SYMBOL_TYPE?{returnwith(session){resolveSymbol()}}2d: AddresolveCall()bridge function (only ifKtResolvableCall)Insertafterthe last existingresolveCallbridge (currentlyKtDestructuringDeclarationEntry.resolveCallbridge)andbeforethecollectCallCandidatesbridge./** * Same KDoc as the interface method */// Auto-generated bridge. DO NOT EDIT MANUALLY!KaExperimentalApiKaContextParameterApicontext(session:KaSession)publicfunKtPsiType.resolveCall():CALL_TYPE?{returnwith(session){resolveCall()}}Step 3: KaBaseResolver — add override implementationsFile:analysis/analysis-api-impl-base/src/org/jetbrains/kotlin/analysis/api/impl/base/components/KaBaseResolver.kt3a: AddresolveSymbol()override (always)Insertafterthe last existingresolveSymbolSafe()line (currentlyKtDestructuringDeclarationEntry.resolveSymbol())andbeforeKtReference.resolveToSymbol().finaloverridefunKtPsiType.resolveSymbol():SYMBOL_TYPE?resolveSymbolSafe()3b: AddresolveCall()override (only ifKtResolvableCall)Insertafterthe last existingresolveCallSafe()/resolveSingleCallSafe()line(currentlyKtDestructuringDeclarationEntry.resolveCall()) andbeforeKtElement.resolveToCall().Choose the helper based on the call return type:If CALL_TYPE contains wildcards (*) → useresolveCallSafe():finaloverridefunKtPsiType.resolveCall():CALL_TYPE?resolveCallSafe()If CALL_TYPE is fully specified (no wildcards) → useresolveSingleCallSafe():finaloverridefunKtPsiType.resolveCall():CALL_TYPE?resolveSingleCallSafe()3c: Add tocanBeResolvedAsCall(only ifKtResolvableCall)In thecanBeResolvedAsCallfunction, add a new branchbeforeelse - false:isKtPsiType-trueStep 4: Investigate FIR/FE10 resolver changesThis step requires investigation — do NOT skip it.Read the FIR resolver:File:analysis/analysis-api-fir/src/org/jetbrains/kotlin/analysis/api/fir/components/KaFirResolver.ktThe FIR resolver works by callinggetOrBuildFir(psi)and dispatching on the FIR element type in awhenblock.Investigate:What FIR element type doesgetOrBuildFir(KtPsiType instance)return?Is that FIR element type already handled in thewhenblocks ofperformSymbolResolution()andperformCallResolution()?If NOT handled, add appropriate handling (new branch in thewhen, possibly with unwrapping logic).Examples of when FIR changes were needed:KtDestructuri ngDeclarationEntry→ maps toFirProperty(a declaration), needed to unwrapFirProperty.initializerKtLabelReferenceExpression→ FIR doesn’t have a dedicated label element, needed to extract fromFirThisReceiverExpression.calleeReferenceKtConstructorDelegationReferenceExpression→ needed to addFirReferenceas a handled caseKtReturnExpression→FirReturnExpressionwasn’t handled, added a new branch helperCheck if theBindingContext-based resolution handles the PSI type. Examples of needed changes:KtCallableReferenceExpression→ redirects topsi.callableReferenceKtWhenConditionInRange→ redirects topsi.operationReferenceKtReturnExpression→ custom logic to find enclosing function viaparents()If changes are needed, implement them following the existing patterns in those files.Step 5: Update PSI API dumpRun:./gradlew :compiler:psi:psi-api:updateKotlinAbiThis updatescompiler/psi/psi-api/api/psi-api.apito reflect the new interface implementation.Phase 4: VerifyStep 1: Static analysisRunget_file_problemswitherrorsOnlyfalseon each modified file. Fix any warnings related to the changes.Step 2: Update test data./gradlew updateTestData\\-Porg.jetbrains.kotlin.testDataManager.options.incrementaltrue\\-Porg.jetbrains.kotlin.testDataManager.options.testDataPathanalysis/analysis-api/testData/components/resolver/Step 3: Validate generated test dataRead the newly generated/updated golden.txtfiles and sanity-check:.symbol.txt— should containKaSymbolResolutionSuccesswith the expected symbol type matchingSYMBOL_TYPE.references.txt— should containKaSymbolResolutionSuccesswith the expected symbol representingSYMBOL_TYPE.call.txt— (ifKtResolvableCall) should containKaCallResolutionSuccesswith the expected call typeIf any file showsnullor unexpected resolution failures, investigate whether FIR/FE10 changes (Step 4 in Phase 3) are missingFor quick investigation of individual tests, run on a specific subdirectory or file:# By subdirectory./gradlew manageTestDataGlobally--modecheck --golden-only --test-data-pathanalysis/analysis-api/testData/components/resolver/singleByPsi/specific-subdir/# By individual file./gradlew manageTestDataGlobally--modecheck --test-data-pathanalysis/analysis-api/testData/components/resolver/singleByPsi/subdir/TestName.ktPhase 5: CommitCreate a commit with the message:[Analysis API] resolver: support new API for KtPsiType ^KT-66039Before committing, readdocs/code_authoring_and_core_review.mdfor commit guidelines. 解析器能力扩展_analysis-api-extend-ka-resolver
以下为本文档的中文说明analysis-api-extend-ka-resolver 是 JetBrains 平台中用于扩展 Kotlin 分析 API 解析器能力的技能。该技能的核心功能是为指定的 Kt* PSI(程序结构接口)类型添加 resolveSymbol() 和可选的 resolveCall() 方法支持,通过遵循已有解析器支持提交中建立的标准模式来实现。工作过程分为多个阶段:第一阶段是信息收集,首先在 compiler/psi/ 目录中搜索 PSI 类型的源文件(.java 或 .kt),读取文件以理解类层次结构,检查该类型是否已经实现了 KtResolvable 或 KtResolvableCall 接口;然后检查 KaResolver.kt 文件中是否已存在对该 PSI 类型的支持。使用场景包括:当 JetBrains 平台的 Kotlin 分析引擎需要为新的 PSI 类型添加符号解析和调用解析能力时;在开发 Kotlin 编译器插件或分析工具时需要扩展解析能力时。核心原则是严格遵循现有代码库中已建立的模式,不创造新的解析机制,而是扩展现有的 KaResolver 框架。该技能要求使用者对 Kotlin 编译器的 PSI 系统有深入理解,特别是 KtResolvable 和 KtResolvableCall 接口的语义和实现模式。通过系统化地按照已有提交的模式进行扩展,确保新增的解析支持与现有代码保持一致的风格和质量标准。Add KaResolver support for a PSI typeThis skill addsresolveSymbol()and optionallyresolveCall()support for a givenKt*PSI typeby following the established pattern from existing resolver support commits.The argument is the PSI type name, e.g.KtDestructuringDeclarationEntry.Phase 1: Gather informationFind the PSI type source file.Searchcompiler/psi/forKtPsiType.javaorKtPsiType.kt.Read the file to understand the class hierarchy and whether it already implementsKtResolvableorKtResolvableCall.Check KaResolver for existing support.Readanalysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KaResolver.ktand search for the PSI type. If it already hasresolveSymbol()/resolveCall()methods, inform the user and stop.Check for existing test data.Searchanalysis/analysis-api/testData/components/resolver/for test filesmentioning the PSI type or related scenarios.Read the Analysis API AGENTS.mdatanalysis/AGENTS.mdfor area-specific guidelines.Phase 2: Ask user questionsUseAskUserQuestionto ask these questions (all in one call):Question 1: Resolution kindHeader:“Resolution”Question:“ShouldKtPsiTypesupport symbol-only resolution (KtResolvable) or both symbol and call resolution (KtResolvableCall)?”KtResolvable— symbol resolution only (resolveSymbol())KtResolvableCall— both symbol and call resolution (resolveSymbol()resolveCall())Question 2: Symbol return typeHeader:“Symbol type”Question:“What shouldresolveSymbol()return forKtPsiType?”KaConstructorSymbolKaFunctionSymbolKaNamedFunctionSymbolKaCallableSymbol(Allow “Other” for types likeKaDeclarationSymbol, etc.)Question 3: Call return type (only ifKtResolvableCall)Header:“Call type”Question:“What shouldresolveCall()return forKtPsiType?”KaFunctionCallKaConstructorSymbolKaDelegatedConstructorCallKaAnnotationCallKaFunctionCallKaNamedFunctionSymbol(Allow “Other” for types likeKaSingleCall*, *,KaFunctionCall*, etc.)Phase 3: Execute changesUse the answers from Phase 2 to determine:RESOLUTION_KIND(KtResolvableorKtResolvableCall),SYMBOL_TYPE(e.g.KaCallableSymbol), andCALL_TYPE(e.g.KaSingleCall*, *).Step 1: PSI type — add interface implementationFile:The PSI source file found in Phase 1 (undercompiler/psi/).If the PSI type does NOT already implementKtResolvable/KtResolvableCall, add it:ForKtResolvable: addimplements KtResolvable(Java) or: KtResolvable(Kotlin)ForKtResolvableCall: addimplements KtResolvableCall(Java) or: KtResolvableCall(Kotlin)KtResolvableCallextendsKtResolvable, so only one is needed.Add the necessary import (org.jetbrains.kotlin.resolution.KtResolvableororg.jetbrains.kotlin.resolution.KtResolvableCall).Step 2: KaResolver interface — add methodsFile:analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KaResolver.kt2a: AddresolveSymbol()interface methodInsertafterthe last existing typedresolveSymbol()method (currentlyKtDestructuringDeclarationEntry.resolveSymbol())andbeforetryResolveCall().Follow the exact KDoc pattern — copy from a similar existing method and adapt:/** * Resolves the description by the given [KtPsiType]. * * #### Example * * kotlin * code example with // ^^^^ markers * * * Calling resolveSymbol() on a [KtPsiType] ... returns the [SYMBOL_TYPE] ... * if resolution succeeds; otherwise, it returns null (e.g., when unresolved or ambiguous). * * This is a specialized counterpart of [KtResolvable.resolveSymbol] focused specifically on description * * see tryResolveSymbols * see KtResolvable.resolveSymbol */KaExperimentalApipublicfunKtPsiTy pe.resolveSymbol():SYMBOL_TYPE?2b: AddresolveCall()interface method (only ifKtResolvableCall)Insertafterthe last existing typedresolveCall()method (currentlyKtDestructuringDeclarationEntry.resolveCall())andbeforecollectCallCandidates()./** * Resolves the given [KtPsiType] to a call description. * * #### Example * * kotlin * code example with // ^^^^ markers * * * Returns the corresponding [CALL_TYPE short name] if resolution succeeds; otherwise, it returns null * (e.g., when unresolved or ambiguous). * * This is a specialized counterpart of [KtResolvableCall.resolveCall] focused specifically on description * * see tryResolveCall * see KtResolvableCall.resolveCall */KaExperimentalApipublicfunKtPsiType.resolveCall():CALL_TYPE?2c: AddresolveSymbol()bridge functionInsertafterthe last existingresolveSymbolbridge (currentlyKtDestructuringDeclarationEntry.resolveSymbolbridge)andbeforethetryResolveCallbridge./** * Same KDoc as the interface method */// Auto-generated bridge. DO NOT EDIT MANUALLY!KaExperimentalApiKaContextParameterApicontext(session:KaSession)publicfunKtPsiType.resolveSymbol():SYMBOL_TYPE?{returnwith(session){resolveSymbol()}}2d: AddresolveCall()bridge function (only ifKtResolvableCall)Insertafterthe last existingresolveCallbridge (currentlyKtDestructuringDeclarationEntry.resolveCallbridge)andbeforethecollectCallCandidatesbridge./** * Same KDoc as the interface method */// Auto-generated bridge. DO NOT EDIT MANUALLY!KaExperimentalApiKaContextParameterApicontext(session:KaSession)publicfunKtPsiType.resolveCall():CALL_TYPE?{returnwith(session){resolveCall()}}Step 3: KaBaseResolver — add override implementationsFile:analysis/analysis-api-impl-base/src/org/jetbrains/kotlin/analysis/api/impl/base/components/KaBaseResolver.kt3a: AddresolveSymbol()override (always)Insertafterthe last existingresolveSymbolSafe()line (currentlyKtDestructuringDeclarationEntry.resolveSymbol())andbeforeKtReference.resolveToSymbol().finaloverridefunKtPsiType.resolveSymbol():SYMBOL_TYPE?resolveSymbolSafe()3b: AddresolveCall()override (only ifKtResolvableCall)Insertafterthe last existingresolveCallSafe()/resolveSingleCallSafe()line(currentlyKtDestructuringDeclarationEntry.resolveCall()) andbeforeKtElement.resolveToCall().Choose the helper based on the call return type:If CALL_TYPE contains wildcards (*) → useresolveCallSafe():finaloverridefunKtPsiType.resolveCall():CALL_TYPE?resolveCallSafe()If CALL_TYPE is fully specified (no wildcards) → useresolveSingleCallSafe():finaloverridefunKtPsiType.resolveCall():CALL_TYPE?resolveSingleCallSafe()3c: Add tocanBeResolvedAsCall(only ifKtResolvableCall)In thecanBeResolvedAsCallfunction, add a new branchbeforeelse - false:isKtPsiType-trueStep 4: Investigate FIR/FE10 resolver changesThis step requires investigation — do NOT skip it.Read the FIR resolver:File:analysis/analysis-api-fir/src/org/jetbrains/kotlin/analysis/api/fir/components/KaFirResolver.ktThe FIR resolver works by callinggetOrBuildFir(psi)and dispatching on the FIR element type in awhenblock.Investigate:What FIR element type doesgetOrBuildFir(KtPsiType instance)return?Is that FIR element type already handled in thewhenblocks ofperformSymbolResolution()andperformCallResolution()?If NOT handled, add appropriate handling (new branch in thewhen, possibly with unwrapping logic).Examples of when FIR changes were needed:KtDestructuri ngDeclarationEntry→ maps toFirProperty(a declaration), needed to unwrapFirProperty.initializerKtLabelReferenceExpression→ FIR doesn’t have a dedicated label element, needed to extract fromFirThisReceiverExpression.calleeReferenceKtConstructorDelegationReferenceExpression→ needed to addFirReferenceas a handled caseKtReturnExpression→FirReturnExpressionwasn’t handled, added a new branch helperCheck if theBindingContext-based resolution handles the PSI type. Examples of needed changes:KtCallableReferenceExpression→ redirects topsi.callableReferenceKtWhenConditionInRange→ redirects topsi.operationReferenceKtReturnExpression→ custom logic to find enclosing function viaparents()If changes are needed, implement them following the existing patterns in those files.Step 5: Update PSI API dumpRun:./gradlew :compiler:psi:psi-api:updateKotlinAbiThis updatescompiler/psi/psi-api/api/psi-api.apito reflect the new interface implementation.Phase 4: VerifyStep 1: Static analysisRunget_file_problemswitherrorsOnlyfalseon each modified file. Fix any warnings related to the changes.Step 2: Update test data./gradlew updateTestData\\-Porg.jetbrains.kotlin.testDataManager.options.incrementaltrue\\-Porg.jetbrains.kotlin.testDataManager.options.testDataPathanalysis/analysis-api/testData/components/resolver/Step 3: Validate generated test dataRead the newly generated/updated golden.txtfiles and sanity-check:.symbol.txt— should containKaSymbolResolutionSuccesswith the expected symbol type matchingSYMBOL_TYPE.references.txt— should containKaSymbolResolutionSuccesswith the expected symbol representingSYMBOL_TYPE.call.txt— (ifKtResolvableCall) should containKaCallResolutionSuccesswith the expected call typeIf any file showsnullor unexpected resolution failures, investigate whether FIR/FE10 changes (Step 4 in Phase 3) are missingFor quick investigation of individual tests, run on a specific subdirectory or file:# By subdirectory./gradlew manageTestDataGlobally--modecheck --golden-only --test-data-pathanalysis/analysis-api/testData/components/resolver/singleByPsi/specific-subdir/# By individual file./gradlew manageTestDataGlobally--modecheck --test-data-pathanalysis/analysis-api/testData/components/resolver/singleByPsi/subdir/TestName.ktPhase 5: CommitCreate a commit with the message:[Analysis API] resolver: support new API for KtPsiType ^KT-66039Before committing, readdocs/code_authoring_and_core_review.mdfor commit guidelines.