colbymchenry--codegraph/docs/design/function-ref-capture.md

Function-as-value capture (#756) — registration-linking for callbacks

Problem. A function used as a value — passed as an argument, assigned to a function pointer or field, placed in a struct initializer or handler table — produced no edge in any of the 19 tree-sitter languages (probed 2026-06-11; 0/19). callers(my_recv_cb) on a C callback showed nothing but direct calls, so every registered callback looked dead, and the registration sites — the agent's actual next question ("where is this wired up?") — were invisible.

Non-goal, deliberate. Resolving the dispatch (o->cb(x) → the concrete registered function) needs data-flow through struct fields; even an LSP needs fallbacks there (see the #756 thread). Partial coverage is worse than none and a wrong edge is worse than silence — dispatch resolution stays uncovered. What ships is the registration side, which is deterministic: the function's name is literally in the source at the registration site.

Mechanism

capture (tree-sitter.ts walkers, table-driven per language: src/extraction/function-ref.ts)
   → gate (flushFnRefCandidates: same-file fn/method name ∪ imported binding names;
            C-family file-scope initializers skip the gate — see below)
   → unresolved ref, referenceKind 'function_ref' (internal-only kind)
   → resolution (resolveOne branch: resolveViaImport first, then matchFunctionRef —
                 exact name, function/method kinds only, same-family, same-file first,
                 cross-file only when UNIQUE, never fuzzy)
   → edge kind 'references', metadata { fnRef: true, resolvedBy, confidence }

getCallers/getCallees/getImpactRadius already traverse references, so registration sites surface with no graph-layer changes. The MCP callers/callees lists label them "via callback registration".

Capture fires from three walkers (a node is only ever visited by one): visitNode (file/class scope), visitForCallsAndStructure (function bodies), visitPascalBlock (Pascal bodies). Subtrees the walkers consume without descending (top-level variable initializers, class field/property initializers, custom visitNode hooks like Scala's val/var handler) get a candidates-only scanFnRefSubtree that halts at nested function boundaries.

Per-language value positions (probe-verified)

Language	arg	assign RHS	keyed init	list/table	wrapper forms
C / ObjC	argument_list	assignment_expression.right	initializer_pair.value	initializer_list, init_declarator.value	&fn (pointer_expression), @selector(...) (ObjC)
C++	& forms only in args/rhs/varinit	(same — explicit & only)	bare ids at FILE scope only	bare ids at FILE scope only	&fn, &Cls::method (resolved scoped to the class)
TS / JS (tsx/jsx)	arguments	assignment_expression.right	pair.value	array, variable_declarator.value	this.method (member_expression, class-scoped — see rule 3)
Python	argument_list, keyword_argument.value	assignment.right	pair.value	list	self.method (attribute)
Go	argument_list	assignment_statement / short_var_declaration (expression_list)	keyed_element	literal_value, var_spec.value	—
Rust	arguments	assignment_expression.right	field_initializer.value	array_expression, static_item / let_declaration.value	—
Java	argument_list	assignment_expression.right	—	variable_declarator.value	method_reference (Cls::m, this::m) — the only form
Kotlin	value_arguments	assignment (last child)	—	—	callable_reference (::f), navigation_expression this::m
C#	argument_list (argument)	assignment_expression.right (incl. +=)	—	initializer_expression, variable_declarator	this.M (member_access_expression; vendored grammar keeps this anonymous — handled)
Ruby	argument_list	—	pair.value	—	only method(:sym) / &method(:sym) — bare ids are calls/locals in Ruby
Swift	value_arguments (value_argument.value)	assignment.result	(labeled ctor args = args)	array_literal, property_declaration.value	#selector(...)
Scala	arguments	assignment_expression.right	—	val_definition.value (via hook scan)	eta fn _ (postfix_expression)
Dart	arguments (argument)	assignment_expression.right	pair.value	list_literal, static_final_declaration	—
Lua / Luau	arguments	assignment_statement (expression_list.value)	field.value (keyed + positional)	(same)	—
Pascal	exprArgs (via visitPascalBlock)	assignment.rhs (OnFire := Handler)	—	—	@Handler (exprUnary.operand)
PHP	string callables ONLY as args of known core HOFs (usort, array_map, call_user_func*… — PHP_CALLABLE_HOFS), ungated + unique-or-drop (PHP globals aren't imported)	—	—	—	[$this, 'm'] → class-scoped this.m; [Foo::class, 'm'] → qualified; 'Cls::m' → qualified; first-class callable fn(...) already extracts as calls
Ruby hooks	(skip_)?(before|after|around)_* + validate/set_callback/helper_method/rescue_from(with:) symbols → class-scoped this.<sym> (rides the supertype pass: before_action :authenticate → ApplicationController). validates (plural) excluded — its symbols are ATTRIBUTES	—	—	—	symbols under any other call yield nothing

Precision rules (each one bought by a real-repo false positive)

1. The gate (extraction-time): a candidate survives only if its name matches a same-file function/method or an imported binding (referenceKind === 'imports' only — scraping type-annotation references names let locals that shared a type-member's name through; excalidraw).
2. C-family ungated file scope: C has no symbol imports and registers callbacks cross-file at repo scale (redis server.c's command table names handlers from t_*.c). File-scope initializer positions (value/list modes) skip the gate — safe because a C file-scope initializer is a constant-expression context: a bare identifier there can only be a function address (enum/macro names get dropped by the kind filter). Local initializers and assignments stay gated: prev = next, *str = field, arena_ind_prev = arena_ind (redis/jemalloc) each matched a unique same-named function somewhere and produced wrong edges when rhs/varinit were ungated.
3. TS/JS/Python: bare ids resolve to function kind only. A bare identifier can never be a method value in these languages (methods need a receiver — this.m / self.m), so allowing method targets soaked up locals passed as arguments (new Set(selectedPointsIndices); docopt.py's name/match params — excalidraw/fmt A/B findings). TS/JS this.X values are captured as this.-PREFIXED candidates and resolved CLASS-SCOPED (resolveThisMemberFnRef in src/resolution/index.ts): the target must be a function/method whose qualified name shares the from-symbol's class prefix, same file, no fallback of any kind — addEventListener(…, this.onResize) hits the enclosing class's method; this.fonts (a property, post-#808 field classification) and inherited/unknown members yield no edge. Python's self.m form keeps method targets through its own capture shape. C#/Swift/Dart/Java/Kotlin keep method targets (method groups, implicit-self, method references are real method values).
4. C++ is &-explicit (addressOfOnly): bare identifiers qualify only in FILE-scope initializer tables; everywhere else (args, assignments, local braced-init lists {begin, size}) only &fn / &Cls::method count. C++ codebases are dense with generic free-function names (begin, end, out, size, data) colliding with locals, and OUT-OF-LINE member definitions extract as function-kind nodes, defeating the kind filter — bare-id matching on fmt was mostly wrong edges (72 generic-name + 105 member/macro mismatches → after the rule: 22 edges, ~20 genuine gtest member-pointer wirings). &x vs *x share C's pointer_expression; only the & operator qualifies. &Cls::method resolves SCOPED to that class.
5. Swift overload-family refusal: several same-named METHODS in one file (Session.request(...) × N) + a bare identifier = almost always a same-named parameter, not a method value (Alamofire) — refuse rather than guess. A unique method (SwiftUI action: handleTap) still resolves.
6. Param-forward skips: this.status = status / o->cb = cb (assignment whose member name equals the RHS identifier) and Swift/Kotlin labeled args value: value — a forwarded local/parameter whose function value is unknowable; a same-named function elsewhere would be the WRONG target.
7. Destructuring skip: const { center } = ellipse extracts data, never a function alias.
8. Generated/minified files (*.min.js and the codegen patterns in generated-detection.ts) produce no fn-ref candidates — minified single-letter symbols resolve everywhere (Alamofire's vendored jquery).
9. Resolution: function/method kinds only, same language family, never the ref's own node (no self-loops), same-file match first, cross-file only when the name is UNIQUE — ambiguity yields no edge. No fuzzy fallback, ever (matchReference short-circuits function_ref refs to matchFunctionRef).
10. Runaway invariant (#760): matchFunctionRef always returns original: ref — the stored row — so deleteSpecificResolvedReferences drains the batch.

Validation (2026-06-11, EXTRACTION_VERSION 19)

Stash-free A/B (baseline = worktree at main), fresh shallow clones, public OSS only. Per repo: node count must be identical, calls edges identical, references strictly additive, precision spot-checked by reading the source line of sampled fnRef edges.

Final build, all 17 repos (nodes identical and calls edges untouched on every row; unresolved_refs fully drained — no batched-resolver runaway):

Lang	Repo	Nodes (base=fix)	calls Δ	refs gained	Notes
C	redis	18931	0/0	+1918	30/30 sample genuine — ops tables, qsort comparators, module registration, lua lib tables
TS/React	excalidraw	10299	0/0	+121	18/20 — residual = param shadowing an imported function (file-level dep real)
Go	gin	2599	0/0	+14
Rust	bytes	947	0/0	+76	map(fn), struct init
Java	okhttp	16008	0/0	+2	method-ref forms only, by design
Kotlin	okio	7801	0/0	+1	::fn forms only, by design
Swift	alamofire	3477	0/0	+116	adversarial case (params mirror API names); overload-family + label==name rules applied
Python	flask	2705	0/0	+111	8/8 sample genuine — incl. ensure_sync(self.dispatch_request)
Ruby	sinatra	1751	0/0	+8	method(:sym) only
C#	newtonsoft	20208	0/0	+38	method groups, +=
Scala	scopt	694	0/0	+10	eta-expansion
Dart	provider	1154	0/0	+73	implicit-this getter reads — true same-class dependencies
Lua	busted	1257	0/0	+14
Luau	fusion	2126	0/0	+18	:Connect(fn)
ObjC	afnetworking	1487	0/0	+52	@selector, target-action
Pascal	pascalcoin	48788	0/0	+577	OnClick := event wiring + paren-less-call refs (see limits)
C++	fmt	7345	0/0	+22	~20/22 genuine gtest member-pointer plumbing after addressOfOnly

Index cost on redis: +6% time, +5% db size.

Known limits (documented, deliberate)

• Dispatch resolution (o->cb(x) → implementations): uncovered, see above.
• C cross-file in gated positions: an extern callback registered via assignment in a different file than its definition only resolves when the name is repo-unique (initializer tables don't have this limit — they're ungated at file scope).
• C++ bare-name registration (register_handler(my_cb) without &): dropped by addressOfOnly — the generic-name collision rate made bare ids net-negative on real C++ (fmt). &my_cb / file-scope tables cover the idioms; C files keep bare args.
• Local/param shadowing an imported or same-file function (mutateElement(newElement, …) where the file also imports newElement; JS plugins' indexOf(val) with a same-file val() helper): irreducible without local-scope tracking — the data-flow frontier deliberately left uncovered. ~1-2 per 20 sampled edges on callback-heavy repos; the file-level dependency is real in every observed case.
• Swift same-class param collisions (eventMonitor?.request(self, didFailTask: task…) where the enclosing type ALSO has a task method): enclosing-type scoping (implicit self — methods match only the from-symbol's own type, top-level bare ids never match methods) eliminated the CROSS-class collision class on Alamofire (−44 wrong edges), but a parameter named after a method of the SAME type is statically indistinguishable from an implicit-self method value. Residual, documented.
• Pascal paren-less calls (Result := DoInitialize): captured as references (Pascal can't distinguish a procedure VALUE from a paren-less CALL without types). The dependency direction is correct and these calls were previously invisible entirely (#791) — strictly more truth, imperfect label.
• Java/Kotlin method refs through a VARIABLE (subscriber::onNext, m::run0): receiver type unknown statically — deliberately no edge (the obj.method class). RxJava's baseline bare capture was resolving these to same-named same-file methods (a test method "registering" an anonymous class's onNext); the qualified rework drops them. Type::method resolves cross-file (scope gated on same-file types ∪ imported names, incl. the last segment of dotted JVM imports); this::m / super::m ride the class-scoped + supertype path.
• Qualified Type::member candidates skip the name gate (like this.X): Java/Kotlin same-package references and Kotlin companions need NO import, so the gate could never see their scope — and the explicit-ref syntax is self-selecting while resolution stays scope-suffix-anchored + unique-or-drop (a Decoy::handle can't match a KtHandlers::handle ref). This is also what resolves companion-member refs: companions extract TRANSPARENTLY (KtHandlers::handle, method of the class) in real multi-line code. (A single-line class X { companion object { … } } is an upstream tree-sitter-kotlin misparse — ERROR node — and only ever appeared in our own probe fixture; don't chase it.)
• Swift cross-file bare references: Swift sees module-wide symbols without imports, so cross-file bare callbacks only resolve when repo-unique (functions; methods are enclosing-type-only). Cross-TYPE #selector targets (rare — target-action is normally self) are scoped away too.
• obj.method member values where obj isn't this/self: deferred — the receiver's type is statically unknowable without local data-flow.
• PHP strings outside known-HOF positions (a bare 'handler' to an arbitrary function; framework registries like WordPress add_action): deliberately uncaptured — a string is only trustworthy as a callable in a known callable position. Framework registries belong in a frameworks/ resolver if ever added. Ruby symbols outside the hook DSLs likewise.
• The supertype pass is NODE-anchored (file-anchored class node → implements/extends edge targets → contains-anchored member lookup): a name-keyed getSupertypes('Engine') unioned every rails Engine's parents and produced a cross-class wrong edge; the node walk eliminated it (rails +440 → +385, all sampled edges genuine).
• this.X inherited members resolve through the supertype pass (resolveDeferredThisMemberRefs, depth-capped BFS over implements/extends, runs after edges persist — same lifecycle as the #750 conformance pass). Reading a getter into a local (const s = this.snapshot) still produces a references edge to the getter — a true dependency with an imperfect "registration" flavor.