CodeGraph 链式调用解析：让 `Foo.getInstance().bar()` 落到正确的 calls 边（13 种语言机制解析）

CodeGraph 是面向 Claude Code、Codex、Cursor 等编码 Agent 的本地代码知识图谱。当一段代码的调用接收者本身也是一个调用——静态工厂、单例、流式 Builder——例如 Foo.getInstance().bar()，图谱就应该产出一条指向链式方法 bar 的 calls 边，而不是把 bar 错误地挂到任意同名方法上。本文基于仓库设计文档 chained-call-resolution.md，深入拆解 CodeGraph 的“链式静态工厂 / 流式调用解析”机制：它的三段式实现（返回类型捕获、接收者重编码、解析并校验）、跨语言共享的三组解析器、supertype 二次合规（conformance）路径，以及 13 种语言落地、TypeScript/Luau 被刻意跳过的完整决策依据。读完后，你将理解该机制在 src/resolution/name-matcher.ts 与 src/extraction/tree-sitter.ts 中的实际调用链，以及“宁可不产出边，也绝不产出错误边”这一安全不变量是如何落地的。

问题背景：裸名匹配为什么是正确性 Bug

在被该机制解决之前，CodeGraph 对所有静态类型语言的处理方式是：丢弃接收者，只对裸方法名做名称匹配。以文档给出的示例为例：

Foo.getInstance().bar();   // bar() 应解析到 Foo::bar，绝不能是别的类型上同名方法

旧逻辑把这条引用还原成 bar 去库里找同名方法。在文档统计的 9 种语言中，有 7 种会静默地把 bar 挂到某个不相关类型上的同名方法——这不是“少建了边”的覆盖率问题，而是图谱里出现了一条指向错误目标的边，属于正确性 Bug：基于这条边做的“谁调用了 bar”“改动 bar 影响哪些调用点”类分析都会出错。

文档（状态：SHIPPED，覆盖 C++、C、PHP、Java、Kotlin、C#、Swift、Rust、Go、Scala、Dart、Objective-C、Pascal/Delphi 共 13 种语言，跟踪 issue #750）把根因归纳为一句话：要解析链式调用，必须先恢复接收者的类型，而恢复接收者类型的前提是工厂方法有“声明式返回类型”。这条主线决定了后面所有设计，也直接决定了哪些语言能做、哪些语言必须跳过。

三段式机制总览

文档把整个机制拆成三个部分，每部分对应代码库中一个明确的位置：

1. 捕获工厂方法的声明返回类型：每种语言在自己的提取器里实现 getReturnType 钩子，把返回类型写入节点的 return_type 属性（schema v5）。规范化规则包括 *Foo→Foo（去指针/引用）、List<Bar>→List（取泛型基名）、pkg.Foo→Foo（取简单名）、-> Self / : self / this.type → 工厂所在类型自身。
2. 提取时保留链式接收者：src/extraction/tree-sitter.ts（或各语言专用提取器）把 Foo.getInstance().bar() 编码为标记字符串 Foo.getInstance().bar——其中的 (). 标记从不出现在普通引用里，因此解析端可以靠它识别并拆分链式引用。每种语言有一个“接收者门控”，让实例链（如 list.map().filter()）保持裸名，不被重编码。
3. 解析并校验（Resolve AND Validate）：解析时用内层调用的返回类型推断接收者类型，再在该类型上解析外层方法，并且校验方法必须真实存在于该类型（或其遵循的 supertype）上。推断错误时产出无边，而不是错误边。

三个共享解析器都位于 src/resolution/name-matcher.ts，最终都落到同一个 resolveMethodOnType（内含 supertype 遍历）：

解析器	接收者形态	语言
matchCppCallChain	field_expression（Foo::instance().bar）	C++、C
matchScopedCallChain	::（Cls::for($x)->m、Foo::new().bar）	PHP、Rust
matchDottedCallChain	.（Foo.create().bar）	Java、Kotlin、C#、Swift、Go、Scala、Dart

第一段：getReturnType 钩子与返回类型捕获

每种支持的语言在 src/extraction/languages/ 下的提取器注册表中提供 getReturnType。以仓库中的实际注册为例：

• src/extraction/languages/java.ts：getReturnType: extractJavaReturnType，其头部注释即说明是“把 Java 类型节点规范化为链式调用可使用的裸类名”，并且显式排除数组（Foo[] 不是可以调实例方法的接收者）。
• src/extraction/languages/rust.ts、src/extraction/languages/go.ts、src/extraction/languages/scala.ts、src/extraction/languages/php.ts、src/extraction/languages/objc.ts、src/extraction/languages/pascal.ts、src/extraction/languages/dart.ts 等均有对应钩子（例如 Pascal 的 typeref 捕获包括接口返回 IFoo；ObjC 的捕获会跳过 nonnull 等 nullability 限定词）。

这一步是整个机制的“燃料”：解析端拿到 Cls::factory 的 qualifiedName 后，去查工厂方法节点上的 return_type。没有这个属性，链式引用就无从解析——这正是 TypeScript 被跳过的根本原因（见后文）。

第二段：提取时的链式接收者重编码

链式重编码发生在 tree-sitter 通用提取器的调用提取逻辑里。src/extraction/tree-sitter.ts 中可以看到核心分支：当 receiver.type === 'call_expression' 且语言命中门控集合（cpp/c/kotlin/swift/rust/go/scala）时，把内层被调函数文本取出，编码为 <innerCallee>().<method>：

// Encode as `<innerCallee>().<method>`; the `().`
// marker never appears in an ordinary ref, so the resolver can detect
// and split it.
calleeName = reencode ? `${innerCallee}().${methodName}` : methodName;

各语言的“接收者门控”（per-language gate）是这段代码里逐语言判断的部分，其设计意图与文档描述完全一致：

• Kotlin / Swift / Scala：仅当内层被调以大写开头（/^[A-Z]/，即类名、伴生工厂或构造调用，如 Foo.getInstance().bar()、Foo(args).bar()）才重编码；小写开头的实例链（list.filter{}.map{}）类型不可恢复，重编码只会丢掉本可裸名命中的边，因此保持裸名走原有解析路径。
• Rust：仅当内层是 scoped_identifier（关联函数链 Foo::new().bar()）时重编码；x.foo().bar() 这类实例链保持裸名。
• Go：仅当内层是裸 identifier（包级工厂函数 New().Method()）时重编码。
• C/C++：任何内层调用都重编码（openSession()->run() 等）。

这个门控是 A/B 数据中“removed 计数 = 错误边修正而非丢失”的关键：实例链的既有解析路径完全不受影响，只有大写接收者 / 工厂链才会被重新编码，因此旧行为零回归。

第三段：解析器与“解析并校验”

三个共享解析器的实现都在 src/resolution/name-matcher.ts 中，结构高度一致。以最通用的 matchDottedCallChain 为例（name-matcher.ts#L1062）：

1. 用正则 ^(.+)\(\)\.(\w+)$ 拆分出内层调用（如 Foo.getInstance）与外层方法名（bar）；
2. 用 lookupCalleeReturnType 查内层工厂的声明返回类型；
3. 把外层方法交给 resolveMethodOnType(ret, method, ref, ...)，置信度 0.85、resolvedBy 标记为 instance-method。

matchDottedCallChain 里还封装了几处语言特例，均可在源码注释中找到文档对应项：

• Go 变量回退（name-matcher.ts#L1080-L1100）：当内层不是有返回类型捕获的函数（比如 gin 的包级变量 engine() 持有函数值），回退到“按裸名解析方法，但结果仍挂在原始引用上”。源码注释明确记录了这次回退修复的真实事故：如果让合成裸名引用的 referenceName 覆盖原始值，批处理解析器（resolveAndPersistBatched）每轮从 offset 0 重读未解析行、依赖批次后按 referenceName 清理的逻辑，会永远对不上已存储的 inner().method 行——批次永不排空，循环反复解析并重复插入，最终把 gin 图谱膨胀到 5M 条边 / 1.4 GB。文档 Coverage 表中 Go 一行的 “Found + fixed a batched-resolver runaway” 说的就是它。
• 构造接收者：Foo(args).method() 被编码为 Foo().method。仅当语言属于 CONSTRUCTS_VIA_BARE_CALL（源码中的集合为 kotlin、swift、scala、dart、pascal）且内层大写时才把类名本身当接收者类型；Java/C# 的裸 Foo() 是方法调用（构造需要 new），被显式排除。
• ObjC 约定回退（ref.language === 'objc' 分支）：类消息工厂 [X alloc] / [X new] / [X sharedFoo] 按约定返回接收者类 X（instancetype）。当工厂自身的返回类型恢复不到时，直接在 X 上解析并校验——[[X alloc] init] 和单例链由此落地；而“返回类型捕获到了但缺该方法”的情况已在更早一步返回 null（缺方法安全），不会误触发。
• Pascal/Delphi 构造回退（ref.language === 'pascal' 分支）：提取器只重编码 TFoo/IFoo 前缀的链，所以 factoryClass 必为真实类型；未标注返回值的工厂视为构造函数（TFileMem.Create().SetCachePerformance），接收者类型即该类本身。

matchScopedCallChain（name-matcher.ts#L1023）处理 :: 形态：仅当内层含 ::（静态工厂调用）时生效，取出 :: 前的类名，查询返回类型；若返回类型是 self 标记（PHP : self/: static、Rust -> Self 的提取器约定），则解析为工厂所在类自身。matchCppCallChain（name-matcher.ts#L1001）形态相同，只是接收者类型由 resolveCppCallResultType 推断（覆盖 field_expression 与 -> 链）。

resolveMethodOnType：整个机制的安全锚点

resolveMethodOnType（name-matcher.ts#L664）是所有链式解析的终点，也是“宁缺毋错”不变量的实现处。它按方法名 + 限定名后缀（<Type>::<method>）在库中找候选方法：

• 找不到方法 → 在深度上限 4 内递归遍历 context.getSupertypes(...)（supertype 合规遍历），仍找不到才返回 null——错误推断 = 无边；
• 找到多个同名候选时，先用调用方文件 import 的 FQN 消歧（preferredFqn 路径后缀匹配，针对 Java/Kotlin import 场景），再退化为“优先调用点所在文件的定义”（处理跨编译单元的 ODR 同名冲突）；
• 命中后返回 ResolvedRef，由上层写成一条 calls 边。

也就是说，三个链式解析器全部终止在同一个校验函数上：decoy（同名诱饵）/ 缺方法场景天然产不出边，这就是文档所说的 “the decoy / absent-method guarantee that makes this safe to ship”。

合规二次路径：supertype 上的方法（issue #754）

链式方法不一定定义在工厂直接返回的类型上，它可能在返回类型继承/遵循的 supertype 上（继承方法、协议扩展默认方法、trait 默认方法、mixin、内嵌/嵌入字段方法）。第一轮解析时 implements/extends 边还没建好，getSupertypes 是空的，这些引用解析不了。

处理方式是延迟 + 二次解析，代码在 src/resolution/index.ts 中一目了然：

const CHAIN_LANGUAGES = new Set(['java', 'kotlin', 'csharp', 'swift', 'rust', 'go', 'scala', 'dart', 'objc', 'pascal']);
const SCOPED_CHAIN_LANGUAGES = new Set(['rust']);

/** The extractor's chained-receiver encoding: `<inner>().<method>`. */
const CHAIN_SHAPE = /^(.+)\(\)\.(\w+)$/;

第一轮解析中，凡是 calls 引用、语言在 CHAIN_LANGUAGES 内、且 referenceName 匹配链式形状 inner().method 但未命中的引用，被收集进内存中的 deferredChainRefs（index.ts#L1031-L1041）——之所以收在内存里而不是留在库里，是因为批处理解析器会把未解析引用从 DB 中删掉。等主流程把 implements/extends 边建完后，resolveChainedCallsViaConformance()（index.ts#L1278）把这些延迟引用重新送进同一个链式解析器；此时 resolveMethodOnType 内部的 supertype 遍历就能沿着已存在的边找到协议扩展 / trait 默认 / 内嵌结构上的方法。该路径幂等（已解析的引用已被删除，重解是 no-op），并返回新建边数。

这条路径一次性解锁了：Swift 协议扩展方法、Rust trait 默认方法、Go 内嵌结构方法、Dart mixin、Java/Kotlin/C# 继承链——文档记录其真实仓库 A/B 为 arrow +22 / −0。

语言覆盖与真实仓库 A/B 数据

文档对每种语言都要求双重验证：合成 decoy / 缺方法测试 + 真实仓库 A/B（对比引入机制前后图谱中 unique calls 边数）。完整覆盖表如下（数据直接继承自 chained-call-resolution.md）：

语言	PR	接收者形态	真实仓库 A/B（unique calls 边）	备注
C++ / C	#645（#742）	field_expression	—	最初的形态：单例 / 工厂 / 链式 getter
PHP	#608（#749）	:: → ->	—	Cls::for($x)->method() —— Laravel per-tenant 客户例写法；支持 : self/: static
Java	#751	.	Guava +1,507 / −0	纯增量：旧行为是缺边
Kotlin	#752	.	arrow +49 / −438	精度收益：−438 = 测试/文档噪声 + 错边被移除；需要大写接收者门控 + 构造接收者处理
C#	#753	.	Newtonsoft +3 / NodaTime +73 / −0	增量；返回类型来自 returns 字段；扩展方法链正确地不解析
合规路径	#754	（解析器升级）	arrow +22 / −0	supertype 遍历——支撑 Swift 协议扩展、Rust trait、Go 内嵌、Dart mixin、Java/Kotlin/C# 继承链
Swift	#755	.	Alamofire / Kingfisher 0 / 0	中性安全（唯一的流式名本就能裸名命中）；需要嵌套 extension 命名修正（KF.Builder→KF::Builder）
Rust	#757	::	clap +937 / −775	精度收益（622 个错边被重定向到正确目标，净 +162）；-> Self；trait 默认方法走合规路径；单跳
Go	#760	.	gin 净零	New().Method()；内嵌结构走合规路径；变量内层回退；发现并修复了批处理解析器 runaway
Scala	#761	.	gatling +14 / −59	精度收益（−59 = 基线把 stdlib Option/Iterator 的 .map/.flatMap 错挂到 gatling 的 Validation::*）；伴生工厂 + case-class apply
Dart	#762	.	localsend（手写） +17 / −10	精度收益 + 构造函数升为一等公民（工厂/命名构造 Foo.create()/Foo._() 现在会被索引；无名的 Foo() 仍记 instantiates）。dartCtorInfo 用外层类名校验构造身份——处理了 tree-sitter 把 @override (A,B) m() 误解析成构造的问题
Objective-C	#786	消息发送	SDWebImage +35 / −75	精度收益；[[Foo create] doIt] 的链式消息发送。getReturnType 跳过 nullability 限定词（nonnull instancetype）。类消息工厂按约定返回接收者类，[[X alloc] init] / 单例链可解析（经校验）。−75 是错误 init 匹配被重定向到正确类
Pascal/Delphi	#791	.（exprDot）	PascalCoin +19 / −18	精度收益；TFoo.GetInstance().DoIt() 走 exprCall/exprDot。getReturnType 从 typeref 捕获（含接口返回 IFoo）。重编码门控在 Delphi TFoo/IFoo 命名约定上，大写变量链保持裸名。构造函数（无 : TBar）或类型转换 TFoo(x) 在类上解析。−18 中 15 个是 class→interface 的正确重定向（GetInstance(): IAsn1OctetString）
TypeScript	—	.	typeorm +0/−6 · nest +0/−164	评估过，未发布——渐进式类型；见下文
Luau	—	: / .	Fusion +0/−0 · matter +0/−0	评估过，未发布——渐进式类型；增量安全（缺边型缺口、无回归），但真实 Luau 极少标注工厂返回类型，两个基准上 +0。合成场景 Foo.create(): Bar 后接 :doIt() 可用

几个值得留意的解读：

• “removed”不是丢失：A/B 中被移除的边绝大多数是基线裸名匹配挂错的边（Kotlin −438、Rust −775、SDWebImage −75、gatling −59），机制把它们要么修到正确目标、要么按“缺方法”不变量直接不产出。
• Swift 0/0 的正面意义：独特流式方法名本来就能靠裸名唯一命中，重编码不产生回归也不产生增量——这正是“门控保证既有解析不被扰动”的实证。
• Dart 的构造函数一等化是链式工作带来的额外收益：Foo.create() 这类工厂/命名构造从此有节点，无名构造 Foo() 仍归 instantiates 边，语义边界清晰。

重新索引与版本号

文档记录该机制落地时 EXTRACTION_VERSION 推进到 18（C++ 链 → … → Pascal 链 → 无括号调用 → free-routine 归属）。当前仓库中 src/extraction/extraction-version.ts 的值已演进到 25——说明在其后还有其它提取工作叠加；对已有图谱升级提取器，运行 codegraph index -f 强制重建即可拾取新版本。

为什么跳过 TypeScript（以及 Luau）

这是文档中最有决策价值的部分，完整继承如下：

• 机制依赖声明式返回类型。TypeScript 大量依赖类型推断——例如 NestJS 的 Test.createTestingModule(m) { return new TestingModuleBuilder(...) } 并没有 : TestingModuleBuilder 标注，工厂的返回类型根本恢复不到；
• 于是重编码后的链式引用解析不了，反而丢掉了现有解析器本可命中的裸名边。真实仓库 A/B：typeorm 与 nest 上均为 +0 新增，净召回回归（nest −164，主要来自无处不在的 Test.createTestingModule({…}).compile() 模式）；
• 被移除的边大多是错的（基线把 .compile() 误解析到 ModuleCompiler::compile）——即精度为正、召回为负。这与 CodeGraph 的召回优先（recall-first）不变量相悖：机制在不造成伤害的地方也没有贡献任何新增（TS 方法名唯一性足够，裸名本来就命中）。
• 该实现当时是完整的（5 个合成测试通过、含 runaway 安全的裸名回退），属于有意不发布。文档指出 TS 唯一可能赢的路径是读取推断出的返回类型（在工厂函数体内解析 return new X()），那是一个大得多的改动。完整分析记录在 issue #750。

Luau 同理：渐进式类型、增量安全（缺边缺口、无回归），但真实 Luau 很少标注工厂返回类型，Fusion 与 matter 两个基准均 +0，故评估后跳过。

全语言分类：21 种语言怎么归类

机制的真正要求是“可靠的声明式返回类型”，而不是笼统的“静态类型”（PHP 靠 : self / : Type 返回声明同样合格）。对照 README 的完整支持语言清单（README.md），文档给出如下分类：

分组	语言
已覆盖（13）	C++、C、PHP、Java、Kotlin、C#、Swift、Rust、Go、Scala、Dart、Objective-C、Pascal/Delphi
评估后跳过（2）	TypeScript——渐进式类型，推断型工厂无法恢复；净召回回归。Luau——渐进式类型；增量安全但 Fusion 与 matter 均 +0（真实 Luau 很少标注工厂返回）。共同原因：机制需要可靠声明的返回类型，渐进式类型的代码太经常省略
Pascal 调用覆盖跟进（2 项缺口，均已解决）	无括号调用（#793）：Pascal 允许无参方法省略括号（Obj.Free;、TFoo.GetInstance.DoIt;），此前解析为裸 exprDot、完全不被提取为调用。现已提取，并限定在语句位置（赋值/条件位置的裸点保持不动——与字段/属性访问有歧义）。PascalCoin A/B +1,131 / −1，新增边全部落到方法。free-routine 归属（#795）：只在 implementation 段定义、无接口声明、非方法的过程/函数此前没有节点，其体内调用被 lump 到文件级；现在它获得函数节点、调用归属到它。PascalCoin A/B +511 / −145（文件级聚合 → 按例程的边）
范围外——无声明式返回类型（6）	JavaScript、Ruby、Lua、Svelte、Vue、Liquid（Liquid 根本没有方法/链式）
部分 / 独立处理（1）	Python——只有可选的 -> T 注解；作为 #578 单独跟踪，不属于本机制

文档还复盘了范围扩张过程：#750 最初框定为“README 里 9 种静态类型语言”，这个枚举是不完整的——漏掉了 Objective-C（同型错误边缺口，机制直接移植，#786 落地）、Pascal/Delphi（一次干净移植；早期“被阻塞”的判断是错的，因为当时只探测了无括号形态）、Luau（评估后跳过）。贯穿线索：机制适配有可靠声明返回类型的语言（13 种已落地）；渐进式类型语言（TypeScript、Luau）省略太频繁，投产比不划算；动态类型语言根本没有返回类型。

边界情况与设计模型

文档最后明确列出了三条边界约定，它们定义了该机制的能力边界：

• 单跳（Single-hop）：一次重编码只覆盖一跳。更深的链（a.b().c().d()）保持裸名——内层 () 破坏了 Class::method 拆分假设。文档标注了对深 fluent-builder 仓库的复测计划；
• 校验而非猜测：每个解析器都终止于 resolveMethodOnType，未知/错误推断类型产出无边——这正是 decoy / 缺方法保证，也是该机制可以安全发布的理由；
• 按语言的接收者门控让实例链保持裸名，既有解析路径永不回归；A/B 表中的 “removed” 计数是错边修正，不是能力丢失。

与动态分派 / 回调合成的边界

文档特意划清了与另一套机制的边界：observer / EventEmitter / React-render / JSX-child / django-ORM 的边合成属于动态分派 / 回调合成，记录在 callback-edge-synthesis.md 与 dynamic-dispatch-coverage-playbook.md。链式解析只处理“静态可知的工厂/流式链”这一类；两套机制解决的问题、输入信号（声明式返回类型 vs 运行时注册点）完全不同，引用时不应混用。

小结

CodeGraph 的链式调用解析机制是一套“捕获声明式返回类型 → 提取期重编码接收者 → 解析并强制校验”的三段式管线：getReturnType 钩子提供类型燃料（src/extraction/languages/ 各语言提取器），tree-sitter 提取器按语言门控把 Foo.getInstance().bar() 编码为 Foo.getInstance().bar（src/extraction/tree-sitter.ts），三组共享解析器与 resolveMethodOnType 保证“推断错误 = 无边”（src/resolution/name-matcher.ts），CHAIN_LANGUAGES + resolveChainedCallsViaConformance 补齐 supertype 上的方法（src/resolution/index.ts）。它落地于 13 种有可靠声明返回类型的语言，用真实仓库 A/B 证明了“增量语言纯增量、错边语言净精度收益”；对 TypeScript/Luau 则给出了完整的负结果与不发布理由——这篇文档既是一份实现说明书，也是一份关于“何时该做、何时该不做”的决策记录。