auryn-python 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,760 @@
1
+ """Phase 2 of the file-based Python engines: turn per-file raw models into the graph.
2
+
3
+ Runs once, project-wide (imports/inheritance/calls are cross-file), and is parameterized
4
+ by an optional `SemanticOracle`:
5
+
6
+ * oracle=None -> the **ast engine** (zero extra deps): types are `annotated` or
7
+ `unresolved` (never `inferred`); calls resolve only when statically import-bound;
8
+ dynamic dispatch is not attempted (`unresolved_calls` stays empty).
9
+ * oracle=<JediOracle> -> the **jedi engine** (default): unannotated types are *inferred*
10
+ at their source position, and calls resolve by inference -- including receiver-typed
11
+ calls like `conn.execute()` that the ast engine can't reach.
12
+
13
+ Both share the id scheme (ids.py) and the same node/edge model, so their output is
14
+ interchangeable for the backbone; they differ only in how much they resolve, which the
15
+ `type_source`/`resolution` provenance records honestly.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import builtins
21
+ import sys
22
+ from collections.abc import Iterator
23
+ from dataclasses import dataclass, field
24
+ from typing import Protocol
25
+
26
+ from auryn.core.graph_model import GraphEdge, GraphNode
27
+ from auryn.ingestors.python import ids
28
+ from auryn.ingestors.python.raw_model import RawAttribute, RawCall, RawClass, RawFunction, RawModule
29
+
30
+ _PROTOCOL_BASES = {"Protocol", "typing.Protocol"}
31
+ _ABC_BASES = {"ABC", "abc.ABC"}
32
+
33
+ # ADR 0004: classify an unresolved reference so a never-resolves system symbol (malloc/len/
34
+ # os.fork) is distinguishable from a not-yet-ingested sibling repo. `builtins`/stdlib are precise;
35
+ # everything else is `external` -- the candidate a future `ingest` upgrades in place.
36
+ _STDLIB = getattr(sys, "stdlib_module_names", frozenset())
37
+ _BUILTINS = frozenset(dir(builtins))
38
+
39
+
40
+ def _origin(qualifier: str) -> str:
41
+ top = qualifier.split(".", 1)[0] if qualifier else ""
42
+ if top == "builtins":
43
+ return "builtin"
44
+ if top in _STDLIB:
45
+ return "stdlib"
46
+ return "external"
47
+
48
+
49
+ class SemanticOracle(Protocol):
50
+ def infer_type(self, module_path: str, line: int, col: int) -> str | None:
51
+ """Inferred type name at a position, or None when it can't be determined."""
52
+
53
+ def resolve_call(self, module_path: str, line: int, col: int) -> str | None:
54
+ """The callee's dotted target (e.g. "app.db.Connection.execute") at a position, or
55
+ None when the oracle finds nothing. Whether the call is receiver-typed and what the
56
+ receiver type is are derived by the caller from the call shape + this name."""
57
+
58
+
59
+ @dataclass(frozen=True)
60
+ class _Call:
61
+ id: str
62
+ label: str
63
+ resolution: str
64
+ receiver_type: str | None
65
+
66
+
67
+ @dataclass(frozen=True)
68
+ class _External:
69
+ """A reference the resolver could name but that is not defined in this ingest: a stdlib/
70
+ builtin/third-party symbol, or a sibling repo's symbol not yet ingested. Becomes a
71
+ placeholder node keyed by its linkage (ADR 0004)."""
72
+
73
+ qualifier: str # dotted module (top-level symbol) or class qname (method)
74
+ name: str
75
+ label: str = "Function"
76
+
77
+
78
+ @dataclass
79
+ class _ModCtx:
80
+ idx: "_Index"
81
+ import_map: dict
82
+ local_funcs: set
83
+ module_path: str
84
+ module_dotted: str
85
+ oracle: SemanticOracle | None
86
+
87
+
88
+ class _Index:
89
+ """Project-wide lookups built before emission."""
90
+
91
+ def __init__(self, proj_id: str, modules: list[RawModule] = ()):
92
+ self.proj_id = proj_id
93
+ self.packages: set[str] = set()
94
+ # Every importable project module/package dotted path -- so an import can be told
95
+ # apart from an external one (only project targets get an IMPORTS edge).
96
+ self.module_dotteds: set[str] = set()
97
+ self.class_by_qname: dict[str, str] = {}
98
+ self.callable_by_qname: dict[str, tuple[str, str]] = {} # qname -> (id, "Function"|"Method")
99
+ self.parents: dict[str, list[str]] = {}
100
+ self.emitted_externs: set[str] = set() # placeholder ids already emitted this pass (dedup)
101
+ for m in modules:
102
+ self.add_module(m)
103
+
104
+ def add_module(self, m: RawModule) -> None:
105
+ """Index one module's symbol contributions. Factored out of __init__ so build_plan
106
+ (streaming) can feed modules one at a time as it loads them, dropping each after."""
107
+ if m.dotted:
108
+ self.module_dotteds.add(m.dotted)
109
+ if m.is_package:
110
+ self.packages.add(m.dotted)
111
+ scope_id = _scope_id(self.proj_id, m)
112
+ for fn in m.functions:
113
+ self.callable_by_qname[f"{m.dotted}.{fn.name}"] = (
114
+ ids.function_id(scope_id, fn.name, [p.name for p in fn.params]),
115
+ "Function",
116
+ )
117
+ for cls in m.classes:
118
+ self._index_class(cls, m.dotted, scope_id)
119
+
120
+ def _index_class(self, cls: RawClass, scope_dotted: str, scope_id: str):
121
+ qname = f"{scope_dotted}.{cls.name}"
122
+ cls_id = ids.class_id(scope_id, cls.name)
123
+ self.class_by_qname[qname] = cls_id
124
+ for method in cls.methods:
125
+ self.callable_by_qname[f"{qname}.{method.name}"] = (
126
+ ids.method_id(cls_id, method.name, [p.name for p in method.params]),
127
+ "Method",
128
+ )
129
+ for nested in cls.nested:
130
+ self._index_class(nested, qname, cls_id)
131
+
132
+ def container_package(self, dotted: str) -> str | None:
133
+ parts = dotted.split(".")
134
+ for cut in range(len(parts) - 1, 0, -1):
135
+ prefix = ".".join(parts[:cut])
136
+ if prefix in self.packages:
137
+ return prefix
138
+ return None
139
+
140
+
141
+ def _scope_id(proj_id: str, m: RawModule) -> str:
142
+ """The id that owns a module's top-level symbols: the Package node for an __init__.py
143
+ (so its classes/functions are emitted and reachable, not dropped), else the Module node."""
144
+ return ids.package_id(proj_id, m.dotted) if m.is_package else ids.module_id(proj_id, m.dotted)
145
+
146
+
147
+ def resolve(modules: list[RawModule], proj_id: str, oracle: SemanticOracle | None = None) -> Iterator[GraphNode | GraphEdge]:
148
+ idx = _Index(proj_id, modules)
149
+ yield from _emit_packages(idx)
150
+ for m in modules:
151
+ yield from _emit_module(m, idx, oracle)
152
+
153
+
154
+ @dataclass
155
+ class GraphIndex:
156
+ """The subset of `_Index` that resolution needs from *other* modules to resolve one
157
+ module's cross-file references -- and that is exactly reproducible from the graph
158
+ (qnames + ids are stored precisely; ids never embed volatile inferred types). Used by
159
+ `resolve_incremental` to seed the symbol table for modules it is NOT re-emitting, so an
160
+ incremental resync can parse+emit only the changed/affected modules while still binding
161
+ their calls/bases/returns to untouched project symbols. See ADR 0002."""
162
+
163
+ packages: set[str] = field(default_factory=set)
164
+ module_dotteds: set[str] = field(default_factory=set)
165
+ class_by_qname: dict[str, str] = field(default_factory=dict)
166
+ callable_by_qname: dict[str, tuple[str, str]] = field(default_factory=dict)
167
+ parents: dict[str, list[str]] = field(default_factory=dict)
168
+
169
+
170
+ def resolve_incremental(
171
+ emit_modules: list[RawModule], proj_id: str, seed: GraphIndex, oracle: SemanticOracle | None = None
172
+ ) -> Iterator[GraphNode | GraphEdge]:
173
+ """Resolve+emit ONLY `emit_modules` (the changed+affected set), binding their references
174
+ against a symbol table = these modules' own symbols merged over `seed` (every OTHER
175
+ module's symbols, read back from the graph). The output is the target subgraph for
176
+ exactly the emit set -- a scoped read-back + compute_delta then reconciles it. See
177
+ incremental.py for the orchestration and the correctness argument (ADR 0002).
178
+
179
+ NOTE: `seed.parents` is fully populated up front, whereas `resolve()` builds `parents`
180
+ incrementally in emission order; for cross-module inheritance whose base is defined
181
+ "later", the MRO linearization can differ. That divergence is exactly what the
182
+ equivalence oracle checks for; deep inheritance is out of scope for this fast-engine
183
+ prototype."""
184
+ idx = _Index(proj_id, emit_modules)
185
+ idx.packages |= seed.packages
186
+ idx.module_dotteds |= seed.module_dotteds
187
+ for qname, cid in seed.class_by_qname.items():
188
+ idx.class_by_qname.setdefault(qname, cid)
189
+ for qname, target in seed.callable_by_qname.items():
190
+ idx.callable_by_qname.setdefault(qname, target)
191
+ for qname, bases in seed.parents.items():
192
+ idx.parents.setdefault(qname, bases)
193
+
194
+ for dotted in sorted({m.dotted for m in emit_modules if m.is_package and m.dotted}):
195
+ yield from _emit_one_package(idx, dotted)
196
+ for m in emit_modules:
197
+ yield from _emit_module(m, idx, oracle)
198
+
199
+
200
+ # -- streaming resolution (memory-bounded: source re-parsed per module, none held) ----------
201
+ #
202
+ # resolve() holds every RawModule (all def/class source text) in memory at once; for a large
203
+ # first ingest that dominates peak RSS. build_plan() instead scans each module once to build
204
+ # only the lightweight _Index (qname -> id tables, no source), and emit_streaming() emits the
205
+ # SAME nodes/edges but loads one module at a time. Because Python resolves relative imports at
206
+ # PARSE time (from the module's dotted path), a blob-sha pickle cache would be stale on a move;
207
+ # ast.parse is cheap, so load_fn just re-parses the blob -- always with the current layout.
208
+ # `idx.parents` is (re)built during emission in module order, NOT up front, so the MRO matches
209
+ # resolve() exactly (up-front parents is resolve_incremental's behaviour -- see its note).
210
+
211
+
212
+ @dataclass
213
+ class StreamPlan:
214
+ idx: _Index
215
+ module_refs: list # [(path, blob_sha)]
216
+ broken: list # paths that failed to parse (parse_ok False)
217
+
218
+
219
+ def build_plan(module_refs, load_fn, proj_id: str) -> StreamPlan:
220
+ """Phase 1: scan each module once into the lightweight _Index, dropping it after.
221
+ `module_refs` is (path, blob_sha) pairs; `load_fn(path, blob_sha)` returns a fresh
222
+ RawModule (a re-parse of the blob at the current path/layout)."""
223
+ module_refs = list(module_refs)
224
+ idx = _Index(proj_id)
225
+ broken: list[str] = []
226
+ for path, blob_sha in module_refs:
227
+ m = load_fn(path, blob_sha)
228
+ if not m.parse_ok:
229
+ broken.append(m.path)
230
+ idx.add_module(m)
231
+ del m
232
+ return StreamPlan(idx=idx, module_refs=module_refs, broken=sorted(broken))
233
+
234
+
235
+ def emit_streaming(plan: StreamPlan, load_fn, proj_id: str, oracle: SemanticOracle | None = None) -> Iterator[GraphNode | GraphEdge]:
236
+ """Phase 2: yield the same nodes/edges as resolve(), re-loading one module at a time.
237
+ Reuses _emit_packages/_emit_module unchanged. Safe to iterate repeatedly (each call
238
+ reloads and resets the per-pass state) -- stream_apply iterates it twice. `idx.parents`
239
+ and `idx.emitted_externs` are reset per call so each pass rebuilds them in module order,
240
+ matching resolve()'s single-pass behaviour; a cross-module edge is still written only once
241
+ every node exists, because stream_apply writes all nodes before any edge."""
242
+ idx = plan.idx
243
+ idx.parents = {}
244
+ idx.emitted_externs = set()
245
+ yield from _emit_packages(idx)
246
+ for path, blob_sha in plan.module_refs:
247
+ m = load_fn(path, blob_sha)
248
+ yield from _emit_module(m, idx, oracle)
249
+ del m
250
+
251
+
252
+ # -- packages ----------------------------------------------------------------------
253
+
254
+
255
+ def _emit_packages(idx: _Index) -> Iterator[GraphNode | GraphEdge]:
256
+ for dotted in sorted(idx.packages):
257
+ yield from _emit_one_package(idx, dotted)
258
+
259
+
260
+ def _emit_one_package(idx: _Index, dotted: str) -> Iterator[GraphNode | GraphEdge]:
261
+ pkg_id = ids.package_id(idx.proj_id, dotted)
262
+ yield GraphNode("Package", {"id": pkg_id}, {"name": dotted.rsplit(".", 1)[-1], "dotted_path": dotted,
263
+ "linkage_key": ids.extern_module_key(dotted)})
264
+ parent = idx.container_package(dotted)
265
+ if parent:
266
+ yield GraphEdge("HAS_SUBPACKAGE", "Package", {"id": ids.package_id(idx.proj_id, parent)}, "Package", {"id": pkg_id})
267
+ else:
268
+ yield GraphEdge("HAS_PACKAGE", "Project", {"id": idx.proj_id}, "Package", {"id": pkg_id})
269
+
270
+
271
+ # -- modules -----------------------------------------------------------------------
272
+
273
+
274
+ def _emit_module(m: RawModule, idx: _Index, oracle: SemanticOracle | None) -> Iterator[GraphNode | GraphEdge]:
275
+ scope_id = _scope_id(idx.proj_id, m)
276
+ if m.is_package:
277
+ # The Package node + its hierarchy edge are emitted by _emit_packages(); an
278
+ # __init__.py's own top-level symbols hang off that Package node.
279
+ scope_label = "Package"
280
+ else:
281
+ scope_label = "Module"
282
+ yield GraphNode(
283
+ "Module",
284
+ {"id": scope_id},
285
+ {"name": m.dotted.rsplit(".", 1)[-1], "dotted_path": m.dotted, "file_path": m.path,
286
+ "linkage_key": ids.extern_module_key(m.dotted)},
287
+ )
288
+ parent = idx.container_package(m.dotted)
289
+ if parent:
290
+ yield GraphEdge("HAS_MODULE", "Package", {"id": ids.package_id(idx.proj_id, parent)}, "Module", {"id": scope_id})
291
+ else:
292
+ yield GraphEdge("HAS_MODULE", "Project", {"id": idx.proj_id}, "Module", {"id": scope_id})
293
+
294
+ ctx = _ModCtx(
295
+ idx=idx,
296
+ import_map={imp.local: imp for imp in m.imports},
297
+ local_funcs={fn.name for fn in m.functions},
298
+ module_path=m.path,
299
+ module_dotted=m.dotted,
300
+ oracle=oracle,
301
+ )
302
+ for fn in m.functions:
303
+ yield from _emit_function(fn, scope_id, m.dotted, m.dotted, "HAS_FUNCTION", scope_id, scope_label, ctx)
304
+ for cls in m.classes:
305
+ yield from _emit_class(cls, scope_id, m.dotted, scope_id, scope_label, "HAS_CLASS", ctx)
306
+ yield from _emit_imports(m, scope_id, scope_label, idx)
307
+
308
+ # Module-scope (top-level) calls: the Module (or Package, for an __init__.py) node is the
309
+ # CALLS source for a script's driver code -- the only place a non-callable node originates a
310
+ # CALLS edge. Resolved exactly like a function body (same helper), so a top-level `main()`
311
+ # binds to the project function and a top-level `print()` becomes a builtin placeholder.
312
+ mod_call_edges, mod_externals, _ = _resolve_scope_calls(m.calls, scope_label, scope_id, ctx)
313
+ yield from mod_externals
314
+ yield from mod_call_edges
315
+
316
+
317
+ def _emit_imports(m: RawModule, scope_id: str, scope_label: str, idx: _Index) -> Iterator[GraphNode | GraphEdge]:
318
+ """One IMPORTS edge per module this module imports from, aggregating the bound names (a bare
319
+ `import a.b` targets module a.b; `from a.b import C` targets a.b). A project target edges to
320
+ the real Module/Package (`resolution:"resolved"`); an external target (stdlib/third-party or a
321
+ not-yet-ingested sibling repo) edges to a placeholder Module node keyed by linkage
322
+ (`resolution:"external"`, ADR 0004) so the provenance "X came from module B" is kept and can
323
+ later upgrade. A self-import is skipped. Aggregated + name-sorted for determinism."""
324
+ project: dict[str, set[str]] = {}
325
+ external: dict[str, set[str]] = {}
326
+ for imp in m.imports:
327
+ target_module = imp.target if imp.is_module else imp.target.rsplit(".", 1)[0]
328
+ if not target_module or target_module == m.dotted:
329
+ continue
330
+ bucket = project if target_module in idx.module_dotteds else external
331
+ bucket.setdefault(target_module, set()).add(imp.local)
332
+ for target_module in sorted(project):
333
+ if target_module in idx.packages:
334
+ to_label, to_id = "Package", ids.package_id(idx.proj_id, target_module)
335
+ else:
336
+ to_label, to_id = "Module", ids.module_id(idx.proj_id, target_module)
337
+ yield GraphEdge(
338
+ "IMPORTS", scope_label, {"id": scope_id}, to_label, {"id": to_id},
339
+ {"names": sorted(project[target_module]), "resolution": "resolved"},
340
+ )
341
+ for target_module in sorted(external):
342
+ eid = ids.extern_module_key(target_module)
343
+ if eid not in idx.emitted_externs:
344
+ idx.emitted_externs.add(eid)
345
+ yield GraphNode("Module", {"id": eid}, {
346
+ "name": target_module.rsplit(".", 1)[-1],
347
+ "dotted_path": target_module,
348
+ "resolved": False,
349
+ "origin": _origin(target_module),
350
+ "linkage_key": eid,
351
+ })
352
+ yield GraphEdge(
353
+ "IMPORTS", scope_label, {"id": scope_id}, "Module", {"id": eid},
354
+ {"names": sorted(external[target_module]), "resolution": "external"},
355
+ )
356
+
357
+
358
+ # -- classes -----------------------------------------------------------------------
359
+
360
+
361
+ def _emit_class(cls: RawClass, scope_id: str, scope_dotted: str, container_id: str, container_label: str, container_rel: str, ctx: _ModCtx) -> Iterator[GraphNode | GraphEdge]:
362
+ cls_id = ids.class_id(scope_id, cls.name)
363
+ qname = f"{scope_dotted}.{cls.name}"
364
+
365
+ resolved_bases: list[tuple[str, str]] = []
366
+ unresolved_bases: list[str] = []
367
+ for base in cls.bases:
368
+ target = _resolve_type(base, scope_dotted, ctx)
369
+ if target:
370
+ resolved_bases.append(target)
371
+ else:
372
+ unresolved_bases.append(base)
373
+ ctx.idx.parents[qname] = [bq for bq, _ in resolved_bases]
374
+ mro = _linearize(qname, ctx.idx.parents)
375
+
376
+ yield GraphNode(
377
+ "Class",
378
+ {"id": cls_id},
379
+ {
380
+ "name": cls.name,
381
+ "qualified_name": qname,
382
+ "linkage_key": ids.extern_symbol_key(scope_dotted, cls.name),
383
+ "bases": cls.bases,
384
+ "mro": mro,
385
+ "unresolved_bases": unresolved_bases,
386
+ "is_abstract": _is_abstract(cls),
387
+ "is_protocol": any(b in _PROTOCOL_BASES for b in cls.bases),
388
+ "is_dataclass": _is_dataclass(cls),
389
+ "decorators": cls.decorators,
390
+ "source": cls.source,
391
+ "doc": cls.doc,
392
+ "line_start": cls.line_start,
393
+ "line_end": cls.line_end,
394
+ },
395
+ )
396
+ yield GraphEdge(container_rel, container_label, {"id": container_id}, "Class", {"id": cls_id})
397
+
398
+ for base_qname, base_id in resolved_bases:
399
+ rel = "IMPLEMENTS" if _looks_like_interface(base_qname) else "EXTENDS"
400
+ props: dict[str, object] = {"resolution": "resolved"}
401
+ if base_qname in mro:
402
+ props["mro_index"] = mro.index(base_qname)
403
+ yield GraphEdge(rel, "Class", {"id": cls_id}, "Class", {"id": base_id}, props)
404
+
405
+ for attr in _dedup_attrs(cls):
406
+ yield from _emit_attribute(attr, cls_id, ctx)
407
+ for method in cls.methods:
408
+ yield from _emit_function(method, cls_id, qname, scope_dotted, "HAS_METHOD", cls_id, "Class", ctx)
409
+ for nested in cls.nested:
410
+ yield from _emit_class(nested, cls_id, qname, cls_id, "Class", "HAS_NESTED_CLASS", ctx)
411
+
412
+
413
+ def _emit_attribute(attr: RawAttribute, cls_id: str, ctx: _ModCtx) -> Iterator[GraphNode | GraphEdge]:
414
+ attr_id = ids.attribute_id(cls_id, attr.name)
415
+ type_str, source = _type_of(attr.annotation, attr.name_line, attr.name_col, ctx)
416
+ yield GraphNode(
417
+ "Attribute",
418
+ {"id": attr_id},
419
+ {"name": attr.name, "type": type_str, "type_source": source, "defined_in": attr.defined_in, "is_classvar": attr.is_classvar},
420
+ )
421
+ yield GraphEdge("HAS_ATTRIBUTE", "Class", {"id": cls_id}, "Attribute", {"id": attr_id})
422
+
423
+
424
+ # -- functions / methods -----------------------------------------------------------
425
+
426
+
427
+ def _resolve_scope_calls(
428
+ calls: list[RawCall], caller_label: str, caller_id: str, ctx: _ModCtx
429
+ ) -> tuple[list[GraphEdge], list[GraphNode], list[str]]:
430
+ """Resolve the calls made from one scope -- a function/method body OR a module's top-level
431
+ code -- into CALLS edges originating at `caller_id`, the external placeholder nodes those
432
+ calls introduce (ADR 0004, deduped via `idx.emitted_externs`), and the unresolved simple-name
433
+ call texts (jedi engine only, for the node's `unresolved_calls` property). Shared by
434
+ `_emit_function` and `_emit_module` so a top-level call and a function-body call resolve
435
+ identically; only the caller node (`caller_label`/`caller_id`) differs."""
436
+ call_edges: list[GraphEdge] = []
437
+ external_nodes: list[GraphNode] = []
438
+ unresolved_calls: list[str] = []
439
+ for call in calls:
440
+ res = _resolve_call(call, ctx)
441
+ if res is None:
442
+ if ctx.oracle is not None and call.is_simple_name:
443
+ unresolved_calls.append(_call_text(call))
444
+ continue
445
+ if isinstance(res, _External):
446
+ eid = ids.extern_symbol_key(res.qualifier, res.name)
447
+ if eid not in ctx.idx.emitted_externs:
448
+ ctx.idx.emitted_externs.add(eid)
449
+ external_nodes.append(_external_symbol_node(res))
450
+ call_edges.append(
451
+ GraphEdge(
452
+ "CALLS", caller_label, {"id": caller_id}, res.label, {"id": eid},
453
+ {"resolution": "external", "receiver_type": None, "argument_types": [], "type_arguments": []},
454
+ )
455
+ )
456
+ continue
457
+ call_edges.append(
458
+ GraphEdge(
459
+ "CALLS", caller_label, {"id": caller_id}, res.label, {"id": res.id},
460
+ {"resolution": res.resolution, "receiver_type": res.receiver_type, "argument_types": [], "type_arguments": []},
461
+ )
462
+ )
463
+ return call_edges, external_nodes, unresolved_calls
464
+
465
+
466
+ def _emit_function(fn: RawFunction, scope_id: str, qual_prefix: str, scope_dotted: str, container_rel: str, container_id: str, container_label: str, ctx: _ModCtx) -> Iterator[GraphNode | GraphEdge]:
467
+ is_method = container_label == "Class"
468
+ param_names = [p.name for p in fn.params]
469
+ fn_id = ids.method_id(scope_id, fn.name, param_names) if is_method else ids.function_id(scope_id, fn.name, param_names)
470
+ label = "Method" if is_method else "Function"
471
+ annotated_ret = fn.returns is not None
472
+
473
+ # Resolve calls first so `unresolved_calls` can ride on the node we're about to emit.
474
+ # A resolved call edges to the project callable; an _External call edges to a placeholder
475
+ # (ADR 0004) -- surfacing stdlib/builtin/third-party and not-yet-ingested sibling symbols.
476
+ call_edges, external_nodes, unresolved_calls = _resolve_scope_calls(fn.calls, label, fn_id, ctx)
477
+
478
+ props: dict[str, object] = {
479
+ "name": fn.name,
480
+ "qualified_name": f"{qual_prefix}.{fn.name}",
481
+ "linkage_key": ids.extern_symbol_key(qual_prefix, fn.name),
482
+ "signature": _signature(fn),
483
+ "return_type": fn.returns if annotated_ret else "Unknown",
484
+ "return_type_source": "annotated" if annotated_ret else "unresolved",
485
+ "is_async": fn.is_async,
486
+ "is_generator": fn.is_generator,
487
+ "decorators": fn.decorators,
488
+ "unresolved_calls": unresolved_calls,
489
+ "source": fn.source,
490
+ "doc": fn.doc,
491
+ "line_start": fn.line_start,
492
+ "line_end": fn.line_end,
493
+ }
494
+ if is_method:
495
+ props.update(kind=_method_kind(fn), is_abstract=_method_is_abstract(fn), overrides=None)
496
+ yield GraphNode(label, {"id": fn_id}, props)
497
+ yield from external_nodes
498
+ yield GraphEdge(container_rel, container_label, {"id": container_id}, label, {"id": fn_id})
499
+
500
+ for i, p in enumerate(fn.params):
501
+ param_id = ids.parameter_id(fn_id, i, p.name)
502
+ type_str, source = _type_of(p.annotation, p.name_line, p.name_col, ctx)
503
+ yield GraphNode(
504
+ "Parameter",
505
+ {"id": param_id},
506
+ {"name": p.name, "type": type_str, "type_source": source, "kind": p.kind, "position": p.position, "has_default": p.has_default},
507
+ )
508
+ yield GraphEdge("HAS_PARAMETER", label, {"id": fn_id}, "Parameter", {"id": param_id})
509
+
510
+ if annotated_ret:
511
+ target = _resolve_type(fn.returns, scope_dotted, ctx)
512
+ if target:
513
+ yield GraphEdge("RETURNS", label, {"id": fn_id}, "Class", {"id": target[1]}, {"resolution": "resolved"})
514
+
515
+ yield from call_edges
516
+
517
+
518
+ # -- resolution helpers ------------------------------------------------------------
519
+
520
+
521
+ def _type_of(annotation: str | None, line: int, col: int, ctx: _ModCtx) -> tuple[str, str]:
522
+ """(type string, type_source). Annotation wins; else the oracle infers; else unresolved.
523
+ The ast engine (oracle=None) therefore only ever yields 'annotated' or 'unresolved'."""
524
+ if annotation is not None:
525
+ return annotation, "annotated"
526
+ if ctx.oracle is not None:
527
+ inferred = ctx.oracle.infer_type(ctx.module_path, line, col)
528
+ if inferred:
529
+ return inferred, "inferred"
530
+ return "Unknown", "unresolved"
531
+
532
+
533
+ def _resolve_type(expr: str, scope_dotted: str, ctx: _ModCtx) -> tuple[str, str] | None:
534
+ """Bind a base/return type expression to a project-local class -> (qname, class_id).
535
+ Static (import/same-module/qualified); external types return None (properties only)."""
536
+ name = expr.split("[", 1)[0].strip()
537
+ if name in ctx.import_map:
538
+ target = ctx.import_map[name].target
539
+ if target in ctx.idx.class_by_qname:
540
+ return target, ctx.idx.class_by_qname[target]
541
+ same_module = f"{scope_dotted}.{name}"
542
+ if same_module in ctx.idx.class_by_qname:
543
+ return same_module, ctx.idx.class_by_qname[same_module]
544
+ if name in ctx.idx.class_by_qname:
545
+ return name, ctx.idx.class_by_qname[name]
546
+ if "." in name:
547
+ head, _, tail = name.rpartition(".")
548
+ if head in ctx.import_map and ctx.import_map[head].is_module:
549
+ qn = f"{ctx.import_map[head].target}.{tail}"
550
+ if qn in ctx.idx.class_by_qname:
551
+ return qn, ctx.idx.class_by_qname[qn]
552
+ return None
553
+
554
+
555
+ def _project_defines(full_name: str, ctx: _ModCtx) -> bool:
556
+ """A dotted name that names a project entity the call model doesn't turn into an edge (a class
557
+ constructor, a module/package) -- so it must NOT be mistaken for an external placeholder."""
558
+ return (full_name in ctx.idx.class_by_qname
559
+ or full_name in ctx.idx.module_dotteds
560
+ or full_name in ctx.idx.packages)
561
+
562
+
563
+ def _split_qualifier(full_name: str) -> tuple[str, str]:
564
+ qualifier, _, name = full_name.rpartition(".")
565
+ return qualifier, name
566
+
567
+
568
+ def _external_or_none(qualifier: str, name: str, ctx: _ModCtx) -> _External | None:
569
+ """A placeholder is made only for a symbol whose *container* is outside this project (stdlib/
570
+ third-party/another repo). A missing symbol inside a project module/class is an intra-project
571
+ dangling reference, not an external one -- drop it (ADR 0004), so a symbol that only appears
572
+ later doesn't leave a stale `extern://` node behind an incremental resync."""
573
+ if (qualifier in ctx.idx.module_dotteds
574
+ or qualifier in ctx.idx.packages
575
+ or qualifier in ctx.idx.class_by_qname):
576
+ return None
577
+ return _External(qualifier, name)
578
+
579
+
580
+ def _constructor_call(class_qname: str, ctx: _ModCtx) -> _Call | None:
581
+ """Instantiating a project class runs its constructor: redirect the call to the class's own
582
+ `__init__` method when it defines one. A class with no local `__init__` (a default or purely
583
+ inherited constructor) has no node to point at, so no edge is drawn -- matching the no-edge
584
+ convention for a call the model can't name. `resolution="constructor"` marks the edge as
585
+ object construction (not a literal textual call to `__init__`); `receiver_type` is the class's
586
+ simple name, mirroring a receiver-typed method call."""
587
+ ctor = ctx.idx.callable_by_qname.get(f"{class_qname}.__init__")
588
+ if ctor is None:
589
+ return None
590
+ return _Call(ctor[0], ctor[1], "constructor", class_qname.rsplit(".", 1)[-1])
591
+
592
+
593
+ def _resolve_call(call: RawCall, ctx: _ModCtx) -> _Call | _External | None:
594
+ """Resolve a call. Returns a _Call (bound to a project callable), an _External (nameable but
595
+ not defined in this ingest -> a placeholder node, ADR 0004), or None (dynamic / unnameable)."""
596
+ if ctx.oracle is not None:
597
+ full_name = ctx.oracle.resolve_call(ctx.module_path, call.line, call.col)
598
+ if not full_name:
599
+ # The oracle found nothing; still surface a bare builtin call (len(), getattr()).
600
+ if call.is_simple_name and call.name in _BUILTINS:
601
+ return _External("builtins", call.name)
602
+ return None
603
+ target = ctx.idx.callable_by_qname.get(full_name)
604
+ if target is None:
605
+ if full_name in ctx.idx.class_by_qname:
606
+ return _constructor_call(full_name, ctx) # instantiation -> the class's __init__
607
+ if _project_defines(full_name, ctx):
608
+ return None # a project module/class w/o a ctor the call model doesn't edge -> drop
609
+ qualifier, name = _split_qualifier(full_name)
610
+ return _external_or_none(qualifier, name, ctx)
611
+ tid, tlabel = target
612
+ via_member = not call.is_simple_name
613
+ # Derive the receiver type from the target's own qname (e.g.
614
+ # "app.db.Connection.execute" -> "Connection") rather than a second inference.
615
+ receiver_type = full_name.rsplit(".", 2)[-2] if via_member and tlabel == "Method" else None
616
+ return _Call(tid, tlabel, "inferred" if via_member else "resolved", receiver_type)
617
+
618
+ # ast path: import-bound or same-module direct name calls -> project functions first.
619
+ if call.is_simple_name:
620
+ if call.name in ctx.import_map:
621
+ hit = ctx.idx.callable_by_qname.get(ctx.import_map[call.name].target)
622
+ if hit and hit[1] == "Function":
623
+ return _Call(hit[0], "Function", "resolved", None)
624
+ hit = ctx.idx.callable_by_qname.get(f"{ctx.module_dotted}.{call.name}")
625
+ if hit and hit[1] == "Function":
626
+ return _Call(hit[0], "Function", "resolved", None)
627
+ # Instantiation of a statically-nameable project class -> its constructor (same redirect
628
+ # as the jedi path): an import-bound class (`from pkg import Cls; Cls()`) or a same-module
629
+ # one (`class Cls: ...; Cls()`). A class with no local __init__ yields None (no edge).
630
+ if call.name in ctx.import_map and ctx.import_map[call.name].target in ctx.idx.class_by_qname:
631
+ return _constructor_call(ctx.import_map[call.name].target, ctx)
632
+ same_module_cls = f"{ctx.module_dotted}.{call.name}"
633
+ if same_module_cls in ctx.idx.class_by_qname:
634
+ return _constructor_call(same_module_cls, ctx)
635
+ # not a project function -> external when we can name it (import-bound, or a builtin).
636
+ if call.name in ctx.import_map:
637
+ target = ctx.import_map[call.name].target
638
+ if _project_defines(target, ctx):
639
+ return None
640
+ qualifier, name = _split_qualifier(target)
641
+ return _external_or_none(qualifier, name, ctx)
642
+ if call.name in _BUILTINS:
643
+ return _External("builtins", call.name)
644
+ return None
645
+ if call.receiver and call.receiver in ctx.import_map:
646
+ # `receiver.name(...)` where `receiver` is an imported name. The imported thing's dotted
647
+ # target is the container of `name` regardless of whether it's a module (`import pkg.mod as
648
+ # m` / `from pkg import mod`) or a class (`from pkg import Cls`): the linkage key is
649
+ # `<target>::<name>` either way -- a module function keys on the module dotted, a class
650
+ # method keys on the class qname, both == the import target. So we do NOT gate on
651
+ # `is_module` (which is False for every `from X import Y`, the common `from pkg import
652
+ # submodule; submodule.fn()` idiom that otherwise goes undetected -> no cross-repo edge).
653
+ target_dotted = ctx.import_map[call.receiver].target
654
+ full = f"{target_dotted}.{call.name}"
655
+ hit = ctx.idx.callable_by_qname.get(full)
656
+ if hit and hit[1] == "Function":
657
+ return _Call(hit[0], "Function", "resolved", None)
658
+ if full in ctx.idx.class_by_qname:
659
+ return _constructor_call(full, ctx) # `mod.Cls()` -> the class's __init__
660
+ if _project_defines(full, ctx):
661
+ return None
662
+ return _external_or_none(target_dotted, call.name, ctx)
663
+ return None
664
+
665
+
666
+ def _external_symbol_node(ext: _External) -> GraphNode:
667
+ """A placeholder node for an unresolved reference, keyed by its linkage so a later ingest of
668
+ the defining repo merges onto it (ADR 0004). Shape mirrors a real callable so the same
669
+ queries reach it; `resolved:false` + `origin` mark it."""
670
+ eid = ids.extern_symbol_key(ext.qualifier, ext.name)
671
+ return GraphNode(ext.label, {"id": eid}, {
672
+ "name": ext.name,
673
+ "qualified_name": f"{ext.qualifier}.{ext.name}" if ext.qualifier else ext.name,
674
+ "module": ext.qualifier,
675
+ "resolved": False,
676
+ "origin": _origin(ext.qualifier),
677
+ "linkage_key": eid,
678
+ })
679
+
680
+
681
+ def _call_text(call: RawCall) -> str:
682
+ return f"{call.receiver}.{call.name}()" if call.receiver else f"{call.name}()"
683
+
684
+
685
+ def _linearize(qname: str, parents: dict[str, list[str]]) -> list[str]:
686
+ """Best-effort MRO over resolved local ancestors (depth-first, de-duplicated),
687
+ terminated by `object`. Not full C3; honest for the common single-inheritance case."""
688
+ order: list[str] = []
689
+
690
+ def visit(q: str):
691
+ if q in order:
692
+ return
693
+ order.append(q)
694
+ for parent in parents.get(q, []):
695
+ visit(parent)
696
+
697
+ visit(qname)
698
+ order.append("object")
699
+ return order
700
+
701
+
702
+ # -- classification helpers --------------------------------------------------------
703
+
704
+
705
+ def _dedup_attrs(cls: RawClass) -> list[RawAttribute]:
706
+ by_name: dict[str, RawAttribute] = {}
707
+ ordered: list[str] = []
708
+ candidates = list(cls.class_attrs) + [a for method in cls.methods for a in method.self_attrs]
709
+ for attr in candidates:
710
+ existing = by_name.get(attr.name)
711
+ if existing is None:
712
+ by_name[attr.name] = attr
713
+ ordered.append(attr.name)
714
+ elif existing.annotation is None and attr.annotation is not None:
715
+ by_name[attr.name] = attr
716
+ elif existing.defined_in != "__init__" and attr.defined_in == "__init__":
717
+ by_name[attr.name] = attr
718
+ return [by_name[n] for n in ordered]
719
+
720
+
721
+ def _looks_like_interface(base_qname: str) -> bool:
722
+ simple = base_qname.rsplit(".", 1)[-1]
723
+ return simple in {"Protocol", "ABC"} or base_qname in _PROTOCOL_BASES or base_qname in _ABC_BASES
724
+
725
+
726
+ def _is_abstract(cls: RawClass) -> bool:
727
+ if any(b in _ABC_BASES or b.rsplit(".", 1)[-1] == "ABC" for b in cls.bases):
728
+ return True
729
+ return any(_method_is_abstract(m) for m in cls.methods)
730
+
731
+
732
+ def _is_dataclass(cls: RawClass) -> bool:
733
+ if any("dataclass" in d for d in cls.decorators):
734
+ return True
735
+ tails = {b.split("[", 1)[0].rsplit(".", 1)[-1] for b in cls.bases}
736
+ return bool(tails & {"BaseModel", "TypedDict", "NamedTuple"})
737
+
738
+
739
+ def _method_kind(fn: RawFunction) -> str:
740
+ decs = fn.decorators
741
+ if any(d.rsplit(".", 1)[-1] == "staticmethod" for d in decs):
742
+ return "static"
743
+ if any(d.rsplit(".", 1)[-1] == "classmethod" for d in decs):
744
+ return "class"
745
+ if any(d.rsplit(".", 1)[-1] == "property" or d.endswith((".setter", ".getter", ".deleter")) for d in decs):
746
+ return "property"
747
+ return "instance"
748
+
749
+
750
+ def _method_is_abstract(fn: RawFunction) -> bool:
751
+ return any("abstractmethod" in d for d in fn.decorators)
752
+
753
+
754
+ def _signature(fn: RawFunction) -> str:
755
+ parts = []
756
+ for p in fn.params:
757
+ prefix = {"var_positional": "*", "var_keyword": "**"}.get(p.kind, "")
758
+ parts.append(f"{prefix}{p.name}: {p.annotation}" if p.annotation else f"{prefix}{p.name}")
759
+ ret = f" -> {fn.returns}" if fn.returns else ""
760
+ return f"{fn.name}({', '.join(parts)}){ret}"