auryn-java 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,620 @@
1
+ """Project-wide pass (phase 2): turn the per-file RawFile list into graph nodes/edges, applying
2
+ the cross-file decisions a single file can't -- materializing the package tier, resolving
3
+ EXTENDS/IMPLEMENTS and parameter/return/field type references to project types, and best-effort
4
+ call resolution.
5
+
6
+ Adapted from the C# ingestor's resolution (Java is its structural sibling), pared to Java: the
7
+ tier is `Package`; EXTENDS vs IMPLEMENTS needs no naming heuristic because Java exposes the
8
+ single `superclass` separately from the `interfaces` list; and the C# DTO/APIEndpoint layer is
9
+ dropped (a Spring enrichment is the future analog).
10
+
11
+ Name-based only -- this is the fast tree-sitter engine, so every CALLS edge is stamped
12
+ `resolution="name"`. A future deep JDT/javac pass would re-emit the same node ids with a
13
+ stronger provenance (the two-phase model). Ambiguous or unresolved references produce no edge
14
+ rather than a wrong guess -- the same trade-off as the C#/PL/SQL ingestors."""
15
+
16
+ from __future__ import annotations
17
+
18
+ import re
19
+ from collections import defaultdict
20
+ from collections.abc import Iterator
21
+ from dataclasses import dataclass, field
22
+
23
+ from auryn.core.graph_model import GraphEdge, GraphNode
24
+ from auryn.ingestors.java import ids, javamod
25
+ from auryn.ingestors.java.raw_model import RawCall, RawFile, RawMethod, RawType
26
+
27
+ _IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
28
+ # Type tokens that are never a project type -- Java primitives/keywords appearing in type text.
29
+ _NON_TYPE_TOKENS = frozenset(
30
+ {"void", "int", "long", "short", "byte", "char", "boolean", "float", "double",
31
+ "var", "extends", "super"}
32
+ )
33
+
34
+ # ADR 0004: the common `java.lang` types that are implicitly imported (never written as an
35
+ # `import`), so a call on one can still be classified `stdlib` and keyed by its real fqcn even
36
+ # without an import to resolve the simple name. Not exhaustive -- the surface that shows up as a
37
+ # call receiver / `new` target in practice.
38
+ _JAVA_LANG = frozenset({
39
+ "Object", "String", "StringBuilder", "StringBuffer", "CharSequence",
40
+ "Integer", "Long", "Short", "Byte", "Character", "Boolean", "Float", "Double", "Number",
41
+ "Math", "System", "Thread", "Runnable", "Throwable", "Exception", "RuntimeException",
42
+ "Error", "Class", "Enum", "Iterable", "Comparable", "Void",
43
+ })
44
+
45
+
46
+ def _origin(fqcn: str) -> str:
47
+ """Coarse provenance for a placeholder's callee (ADR 0004 §4): a JDK/stdlib symbol (never
48
+ upgraded by a future ingest) vs an `external` one (the candidate a sibling repo defines)."""
49
+ return "stdlib" if fqcn.startswith(("java.", "javax.", "jdk.")) else "external"
50
+
51
+
52
+ @dataclass
53
+ class _Extern:
54
+ """A callee the resolver could NAME but that is not defined in this ingest -- a JDK/stdlib or
55
+ other-repo method. Becomes a placeholder Method keyed by its cross-repo linkage (ADR 0004)."""
56
+ linkage: str # extern://java/<qualified> -- the placeholder id AND its linkage_key
57
+ name: str # the callee's simple name
58
+ qualified: str # <owner fqcn>#<member>, as a consumer would name it
59
+ origin: str # "stdlib" | "external"
60
+ receiver_type: str | None # the receiver's simple type name, when known (kept on the edge)
61
+
62
+
63
+ @dataclass
64
+ class _Entry:
65
+ type_id: str
66
+ kind: str # "Class" | "Interface" | "Enum" | "Record"
67
+ name: str
68
+ package: str
69
+ raw_type: RawType
70
+ file_id: str
71
+ parent_type_id: str | None
72
+ scope_id: str
73
+ scope_label: str | None # "Package" | "Module" (top-level only; None if nested)
74
+ module: str = "" # the declaring file's Maven/Gradle module -- biases same-module resolution
75
+ seed_ctor_id: str | None = None # a NON-emit (seed) type's constructor id, for `new` resolution
76
+
77
+
78
+ @dataclass
79
+ class JavaGraphIndex:
80
+ """Java resolution tables seeded from the GRAPH for the NON-emit files (ADR 0005), so
81
+ `resolve_incremental` can resolve an emit file's cross-file/cross-package refs without re-parsing
82
+ the project. type_index carries lightweight `_Entry` stubs (empty raw_type; `seed_ctor_id` lets a
83
+ `new` target resolve its constructor); method_index/packages mirror what the full resolve builds
84
+ from entries. Reconstructed by `java.incremental.read_java_index`."""
85
+
86
+ packages: set = field(default_factory=set)
87
+ type_index: dict = field(default_factory=dict) # name -> [_Entry stub]
88
+ method_index: dict = field(default_factory=dict) # name -> [(type_id, method_id, package, module)]
89
+
90
+
91
+ def make_type_stub(type_id: str, kind: str, name: str, package: str, module: str, ctor_id: str | None) -> _Entry:
92
+ """A lightweight `_Entry` for a NON-emit type the seed provides: only id/kind/name/package/module
93
+ are needed to point a resolved edge at it (module biases same-module resolution); `ctor_id` (its
94
+ graph constructor, if any) lets an emit file's `new` resolve without the raw type body."""
95
+ return _Entry(type_id, kind, name, package, RawType(kind=kind, name=name, package=package),
96
+ file_id="", parent_type_id=None, scope_id="", scope_label=None, module=module, seed_ctor_id=ctor_id)
97
+
98
+
99
+ def resolve(raw_files: list[RawFile], project_id: str) -> Iterator[GraphNode | GraphEdge]:
100
+ yield from _resolve(raw_files, project_id, seed=None)
101
+
102
+
103
+ def resolve_incremental(emit_raws: list[RawFile], project_id: str, index: JavaGraphIndex) -> list:
104
+ """Emit graph items for ONLY `emit_raws`, resolving cross-file/cross-package refs against `index`
105
+ (graph-seeded non-emit symbols) merged with the emit files' own. The blast-radius analogue of
106
+ resolve() (ADR 0005): same emitters, indices seeded rather than whole-project."""
107
+ return list(_resolve(emit_raws, project_id, seed=index))
108
+
109
+
110
+ def _resolve(raw_files: list[RawFile], project_id: str, seed: "JavaGraphIndex | None") -> Iterator[GraphNode | GraphEdge]:
111
+ # Stable path order so a symbol somehow defined in several files reduces to an order-INDEPENDENT
112
+ # winner -- identical here and in resolve_incremental's subset (ADR 0005). Java forbids duplicate
113
+ # FQNs so this is belt-and-braces, but keeps the invariant the engine relies on.
114
+ raw_files = sorted(raw_files, key=lambda rf: _norm(rf.path))
115
+
116
+ file_ids: dict[str, str] = {}
117
+ imports_by_file: dict[str, dict[str, str]] = {} # file_id -> {simple type name -> fqcn}
118
+ modules_by_path: dict[str, str] = {} # rf.path -> Maven/Gradle module (path-derived scope root)
119
+ file_modules: list[tuple[str, str]] = [] # (file_id, module): File-DEFINES-Module provenance
120
+ file_packages: list[tuple[str, str, str]] = [] # (file_id, module, package): File-DEFINES-Package provenance
121
+ for rf in raw_files:
122
+ fid = ids.file_id(project_id, rf.path)
123
+ file_ids[rf.path] = fid
124
+ imports_by_file[fid] = _import_index(rf)
125
+ module = javamod.module_for_path(rf.path)
126
+ modules_by_path[rf.path] = module
127
+ file_modules.append((fid, module))
128
+ yield GraphNode("File", {"id": fid}, {"name": _basename(rf.path), "path": _norm(rf.path)})
129
+ yield GraphEdge("HAS_FILE", "Project", {"id": project_id}, "File", {"id": fid})
130
+ if rf.package:
131
+ file_packages.append((fid, module, rf.package))
132
+ yield from _emit_modules(file_modules, project_id)
133
+ yield from _emit_packages(file_packages, project_id)
134
+
135
+ emit_entries: list[_Entry] = []
136
+ for rf in raw_files:
137
+ module = modules_by_path[rf.path]
138
+ scope_root = _scope_root(project_id, module)
139
+ for rt in rf.types:
140
+ _flatten(rt, file_ids[rf.path], scope_root, None, rf.package, emit_entries, module)
141
+ # Keep-first dedup by type_id (deterministic winner if an id ever repeats) -- the emitter must
142
+ # emit each node id at most once (the engine's read-back/diff assumes it).
143
+ seen_tids: set[str] = set()
144
+ emit_entries = [e for e in emit_entries if not (e.type_id in seen_tids or seen_tids.add(e.type_id))]
145
+
146
+ # Resolution indices span emit entries + the graph-seeded non-emit symbols, so an emit file's
147
+ # cross-file/cross-package reference still resolves to an untouched target.
148
+ type_index: dict[str, list[_Entry]] = defaultdict(list)
149
+ for e in emit_entries:
150
+ type_index[e.name].append(e)
151
+ method_index: dict[str, list[tuple[str, str, str, str]]] = defaultdict(list)
152
+ for e in emit_entries:
153
+ for m in e.raw_type.methods:
154
+ method_index[m.name].append((e.type_id, _method_id(e.type_id, m), e.package, e.module))
155
+ if seed is not None:
156
+ for name, stubs in seed.type_index.items():
157
+ type_index[name].extend(stubs)
158
+ for name, tuples in seed.method_index.items():
159
+ method_index[name].extend(tuples)
160
+
161
+ # Pass 1: nodes + structural edges (so pass 2's cross-refs always have a landing node). EMIT ONLY
162
+ # the emit entries; seed entries exist purely as resolution targets.
163
+ for e in emit_entries:
164
+ yield from _emit_type_and_members(e)
165
+ # Pass 2: cross-references. `emitted_externs` dedups placeholder nodes across the whole pass
166
+ # so N callers of one JDK/other-repo method MERGE onto a single node (ADR 0004).
167
+ emitted_externs: set[str] = set()
168
+ for e in emit_entries:
169
+ yield from _emit_hierarchy(e, type_index)
170
+ yield from _emit_type_references(e, type_index)
171
+ yield from _emit_calls(e, type_index, method_index, imports_by_file.get(e.file_id, {}), emitted_externs)
172
+
173
+
174
+ # -- modules & packages --------------------------------------------------------------------
175
+
176
+ def _scope_root(project_id: str, module: str) -> str:
177
+ """The id a file's packages/types nest under: the Module node for a real Maven/Gradle subproject,
178
+ or the Project itself for a root-level file (`module == ""`). Keeping root files Project-scoped
179
+ (rather than under a Module named after the project) means a root file and a subproject literally
180
+ named after the project -- both `src/main/java/...` and `<proj>/src/main/java/...` -- can never
181
+ collapse to one id. The Module tier therefore appears only when there genuinely ARE subprojects."""
182
+ return ids.module_id(project_id, module) if module else project_id
183
+
184
+
185
+ def _emit_modules(file_modules: list[tuple[str, str]], project_id: str) -> Iterator[GraphNode | GraphEdge]:
186
+ """Materialize the Maven/Gradle module tier: Project -[:HAS_MODULE]-> Module, one per subproject
187
+ (path-derived, see javamod). The module is the scope root the package tier nests under, so two
188
+ modules' identically-named packages/types stay distinct. Root-level files (`module == ""`) get NO
189
+ Module node -- they hang off the Project directly (see _scope_root). Like Package, a Module is an
190
+ aggregation node many files feed, so it is provenance-owned (File-[:DEFINES]->Module) and reclaimed
191
+ once its last member file is gone (ADR 0005), and excluded from the co-DEFINER winner closure
192
+ (JAVA_SPEC.aggregation_labels). A Java module carries NO linkage_key: a consumer imports by FQCN,
193
+ not by module name, so the module heals nothing (cross-repo linkage stays FQCN-based)."""
194
+ emitted: set[str] = set()
195
+ def_edges: set[tuple[str, str]] = set() # (file_id, module_id), dedup exact repeats
196
+ for file_id, module in file_modules:
197
+ if not module:
198
+ continue # root-level file -> Project-scoped, no Module node
199
+ mid = ids.module_id(project_id, module)
200
+ if mid not in emitted:
201
+ emitted.add(mid)
202
+ yield GraphNode("Module", {"id": mid}, {"name": module})
203
+ yield GraphEdge("HAS_MODULE", "Project", {"id": project_id}, "Module", {"id": mid})
204
+ def_edges.add((file_id, mid))
205
+ for file_id, mid in sorted(def_edges):
206
+ yield GraphEdge("DEFINES", "File", {"id": file_id}, "Module", {"id": mid})
207
+
208
+
209
+ def _emit_packages(file_packages: list[tuple[str, str, str]], project_id: str) -> Iterator[GraphNode | GraphEdge]:
210
+ """Materialize every prefix of every declared package as a Package node (as C# does for
211
+ namespaces), nested under its scope root: the first segment hangs off the file's Module (a
212
+ subproject) or the Project (a root-level file) via HAS_PACKAGE, deeper segments chain via
213
+ HAS_SUBPACKAGE. `com.acme.app` -> Package(com) -> Package(com.acme) -> Package(com.acme.app), all
214
+ keyed under that scope root so two modules' `com.acme` stay distinct.
215
+
216
+ Also emits a File-[:DEFINES]->Package edge from each declaring file to EVERY prefix of its package
217
+ (ADR 0005 GC handle): a prefix Package is reclaimed once its last member file is gone, exactly like
218
+ a full recompute -- otherwise deleting a package's last file strands the (no-longer-owned) Package
219
+ nodes. Package props are id-derived, so Package is excluded from the co-DEFINER winner closure
220
+ (JAVA_SPEC.aggregation_labels): a shared prefix like `com` is co-declared by every file beneath it,
221
+ which would otherwise drag the whole subtree into any one file's resync."""
222
+ emitted: set[str] = set()
223
+ def_edges: set[tuple[str, str]] = set() # (file_id, package_id), dedup exact repeats
224
+ for file_id, module, package in file_packages:
225
+ scope_root = _scope_root(project_id, module)
226
+ prefix = ""
227
+ parent_id, parent_label, parent_rel = scope_root, ("Module" if module else "Project"), "HAS_PACKAGE"
228
+ for segment in package.split("."):
229
+ prefix = f"{prefix}.{segment}" if prefix else segment
230
+ pid = ids.package_id(scope_root, prefix)
231
+ if pid not in emitted:
232
+ emitted.add(pid)
233
+ yield GraphNode("Package", {"id": pid}, {"name": segment, "qualified_name": prefix})
234
+ yield GraphEdge(parent_rel, parent_label, {"id": parent_id}, "Package", {"id": pid})
235
+ def_edges.add((file_id, pid))
236
+ parent_id, parent_label, parent_rel = pid, "Package", "HAS_SUBPACKAGE"
237
+ for file_id, pid in sorted(def_edges):
238
+ yield GraphEdge("DEFINES", "File", {"id": file_id}, "Package", {"id": pid})
239
+
240
+
241
+ # -- flattening ----------------------------------------------------------------------------
242
+
243
+ def _flatten(rt: RawType, file_id: str, scope_root: str, parent_type_id: str | None, package: str,
244
+ entries: list[_Entry], module: str) -> None:
245
+ """`scope_root` is the file's per-file scope root (its Module for a subproject, else the Project --
246
+ see _scope_root), which the package tier and default-package types nest under, so two modules'
247
+ identically-named packages/types stay distinct."""
248
+ if parent_type_id is not None:
249
+ tid = ids.type_id(parent_type_id, rt.kind, rt.name, rt.type_parameters)
250
+ scope_id, scope_label = parent_type_id, None
251
+ elif package:
252
+ scope_id = ids.package_id(scope_root, package)
253
+ scope_label = "Package"
254
+ tid = ids.type_id(scope_id, rt.kind, rt.name, rt.type_parameters)
255
+ else:
256
+ # default-package types hang off the scope root: the Module for a subproject, else the Project.
257
+ scope_id, scope_label = scope_root, ("Module" if module else "Project")
258
+ tid = ids.type_id(scope_id, rt.kind, rt.name, rt.type_parameters)
259
+
260
+ entries.append(_Entry(tid, rt.kind, rt.name, package, rt, file_id, parent_type_id, scope_id, scope_label, module=module))
261
+ for nested in rt.nested_types:
262
+ _flatten(nested, file_id, scope_root, tid, package, entries, module)
263
+
264
+
265
+ # -- pass 1: nodes + structural edges ------------------------------------------------------
266
+
267
+ def _type_properties(rt: RawType) -> dict:
268
+ props: dict = {
269
+ "name": rt.name,
270
+ "qualified_name": f"{rt.package}.{rt.name}" if rt.package else rt.name,
271
+ "accessibility": rt.accessibility,
272
+ "type_parameters": list(rt.type_parameters),
273
+ "annotations": [a.name for a in rt.annotations],
274
+ "source": rt.source,
275
+ "doc": rt.doc,
276
+ "line_start": rt.line_start,
277
+ "line_end": rt.line_end,
278
+ }
279
+ if rt.kind == "Class":
280
+ props.update(is_abstract="abstract" in rt.modifiers, is_final="final" in rt.modifiers,
281
+ is_static="static" in rt.modifiers)
282
+ elif rt.kind == "Record":
283
+ props["components"] = [p.name for p in rt.record_components]
284
+ return props
285
+
286
+
287
+ def _emit_type_and_members(e: _Entry) -> Iterator[GraphNode | GraphEdge]:
288
+ # `module` lets read_java_index reconstruct an incremental stub's module for same-module
289
+ # resolution bias without re-parsing (ADR 0005) -- the only non-id-derivable fact a stub needs.
290
+ yield GraphNode(e.kind, {"id": e.type_id}, {**_type_properties(e.raw_type), "module": e.module})
291
+ if e.parent_type_id is not None:
292
+ yield GraphEdge("HAS_NESTED_TYPE", _parent_kind(e), {"id": e.parent_type_id}, e.kind, {"id": e.type_id})
293
+ else:
294
+ yield GraphEdge("HAS_TYPE", e.scope_label, {"id": e.scope_id}, e.kind, {"id": e.type_id})
295
+ yield GraphEdge("DEFINED_IN", e.kind, {"id": e.type_id}, "File", {"id": e.file_id})
296
+ # Per-file ownership handle for delta-sync (File→entity, ADR 0005; uniform with C/Go). A type and
297
+ # its methods are always co-located in Java, so both DEFINES edges source at the same File.
298
+ yield GraphEdge("DEFINES", "File", {"id": e.file_id}, e.kind, {"id": e.type_id})
299
+
300
+ owner_fqcn = _type_fqcn(e)
301
+ for m in e.raw_type.methods:
302
+ yield from _emit_method(e.type_id, e.kind, m, owner_fqcn, e.file_id)
303
+ for f in e.raw_type.fields:
304
+ yield from _emit_field(e.type_id, e.kind, f)
305
+ for member in e.raw_type.enum_members:
306
+ mid = ids.enum_member_id(e.type_id, member.name)
307
+ yield GraphNode("EnumMember", {"id": mid}, {"name": member.name, "arguments": member.arguments})
308
+ yield GraphEdge("HAS_ENUM_MEMBER", "Enum", {"id": e.type_id}, "EnumMember", {"id": mid})
309
+ for i, comp in enumerate(e.raw_type.record_components): # record components -> Parameters
310
+ yield from _emit_parameter(e.type_id, e.kind, comp, i)
311
+
312
+
313
+ # _parent_kind: the parent entry's kind is needed as the HAS_NESTED_TYPE source label. Nested
314
+ # types are rare enough that a re-derivation via the id suffix is cheaper than threading the
315
+ # parent label through _flatten.
316
+ _KIND_BY_SLUG = {"class": "Class", "interface": "Interface", "enum": "Enum", "record": "Record"}
317
+
318
+
319
+ def _parent_kind(e: _Entry) -> str:
320
+ # parent_type_id ends with ".<slug>.<name>[`arity]"; pull the slug.
321
+ tail = e.parent_type_id.rsplit(".", 2)[-2] if e.parent_type_id else "class"
322
+ return _KIND_BY_SLUG.get(tail, "Class")
323
+
324
+
325
+ def _method_id(type_id: str, m: RawMethod) -> str:
326
+ return ids.method_id(type_id, m.name, [p.type for p in m.parameters])
327
+
328
+
329
+ def _emit_method(type_id: str, type_label: str, m: RawMethod, owner_fqcn: str, file_id: str) -> Iterator[GraphNode | GraphEdge]:
330
+ mid = _method_id(type_id, m)
331
+ props = {
332
+ "name": m.name,
333
+ "kind": m.kind,
334
+ "accessibility": m.accessibility,
335
+ "is_static": "static" in m.modifiers,
336
+ "is_abstract": "abstract" in m.modifiers,
337
+ "is_final": "final" in m.modifiers,
338
+ "return_type": m.return_type,
339
+ "throws": m.throws,
340
+ "annotations": [a.name for a in m.annotations],
341
+ "source": m.source,
342
+ "doc": m.doc,
343
+ "line_start": m.line_start,
344
+ "line_end": m.line_end,
345
+ }
346
+ # ADR 0004: an externally-visible method carries a project-INDEPENDENT cross-repo key, so a
347
+ # placeholder emitted by another repo's call heals onto it (reconcile). Name-based
348
+ # (`owner-fqcn#member`, a constructor's member is the type's simple name); a consumer can't
349
+ # reference a package/private method, so those are left off the cross-repo surface.
350
+ if m.accessibility in ("public", "protected"):
351
+ props["linkage_key"] = ids.extern_method_key(f"{owner_fqcn}#{m.name}")
352
+ yield GraphNode("Method", {"id": mid}, props)
353
+ yield GraphEdge("HAS_METHOD", type_label, {"id": type_id}, "Method", {"id": mid})
354
+ yield GraphEdge("DEFINES", "File", {"id": file_id}, "Method", {"id": mid}) # per-file ownership (ADR 0005)
355
+ for i, p in enumerate(m.parameters):
356
+ yield from _emit_parameter(mid, "Method", p, i)
357
+
358
+
359
+ def _emit_parameter(parent_id: str, parent_label: str, param, position: int) -> Iterator[GraphNode | GraphEdge]:
360
+ pid = ids.parameter_id(parent_id, position, param.name)
361
+ yield GraphNode("Parameter", {"id": pid}, {
362
+ "name": param.name, "type": param.type, "position": param.position,
363
+ "is_varargs": param.is_varargs,
364
+ })
365
+ yield GraphEdge("HAS_PARAMETER", parent_label, {"id": parent_id}, "Parameter", {"id": pid})
366
+
367
+
368
+ def _emit_field(type_id: str, type_label: str, f) -> Iterator[GraphNode | GraphEdge]:
369
+ fid = ids.field_id(type_id, f.name)
370
+ yield GraphNode("Field", {"id": fid}, {
371
+ "name": f.name, "type": f.type, "accessibility": f.accessibility,
372
+ "is_static": "static" in f.modifiers, "is_final": "final" in f.modifiers,
373
+ "annotations": [a.name for a in f.annotations],
374
+ })
375
+ yield GraphEdge("HAS_FIELD", type_label, {"id": type_id}, "Field", {"id": fid})
376
+
377
+
378
+ # -- pass 2: hierarchy, type references, calls ---------------------------------------------
379
+
380
+ def _resolve_target(name: str, type_index: dict[str, list[_Entry]], from_package: str, from_module: str) -> _Entry | None:
381
+ matches = type_index.get(name)
382
+ if not matches:
383
+ return None
384
+ # Bias toward the referrer's own module/package: within one build only the caller's module (plus
385
+ # its deps) is on the classpath, so two modules' same-package `Helper` must not cross-bind. Prefer
386
+ # same-module+same-package, then same-package, then same-module, then anywhere (deterministic).
387
+ same_mod_pkg = [m for m in matches if m.module == from_module and m.package == from_package]
388
+ same_pkg = [m for m in matches if m.package == from_package]
389
+ same_mod = [m for m in matches if m.module == from_module]
390
+ pool = same_mod_pkg or same_pkg or same_mod or matches
391
+ return sorted(pool, key=lambda m: m.type_id)[0] # deterministic on ambiguity
392
+
393
+
394
+ def _emit_hierarchy(e: _Entry, type_index: dict[str, list[_Entry]]) -> Iterator[GraphEdge]:
395
+ rt = e.raw_type
396
+ if rt.superclass: # class -> class
397
+ target = _resolve_target(rt.superclass, type_index, e.package, e.module)
398
+ if target is not None and target.type_id != e.type_id:
399
+ yield GraphEdge("EXTENDS", e.kind, {"id": e.type_id}, target.kind, {"id": target.type_id})
400
+ for iface in rt.interfaces:
401
+ target = _resolve_target(iface, type_index, e.package, e.module)
402
+ if target is None or target.type_id == e.type_id:
403
+ continue
404
+ # an interface's `interfaces` list is really its super-interfaces -> EXTENDS.
405
+ rel = "EXTENDS" if e.kind == "Interface" else "IMPLEMENTS"
406
+ yield GraphEdge(rel, e.kind, {"id": e.type_id}, target.kind, {"id": target.type_id})
407
+
408
+
409
+ def _referenced_names(type_text: str | None) -> list[str]:
410
+ if not type_text:
411
+ return []
412
+ return [n for n in _IDENTIFIER_RE.findall(type_text) if n not in _NON_TYPE_TOKENS]
413
+
414
+
415
+ def _emit_type_references(e: _Entry, type_index: dict[str, list[_Entry]]) -> Iterator[GraphEdge]:
416
+ for m in e.raw_type.methods:
417
+ mid = _method_id(e.type_id, m)
418
+ names = set(_referenced_names(m.return_type))
419
+ for p in m.parameters:
420
+ names.update(_referenced_names(p.type))
421
+ yield from _depends_on("Method", mid, names, e, type_index)
422
+ for f in e.raw_type.fields:
423
+ fid = ids.field_id(e.type_id, f.name)
424
+ yield from _depends_on("Field", fid, set(_referenced_names(f.type)), e, type_index)
425
+
426
+
427
+ def _depends_on(from_label: str, from_id: str, names: set[str], e: _Entry, type_index) -> Iterator[GraphEdge]:
428
+ emitted: set[str] = set()
429
+ for name in names:
430
+ target = _resolve_target(name, type_index, e.package, e.module)
431
+ if target is None or target.type_id == e.type_id or target.type_id in emitted:
432
+ continue
433
+ emitted.add(target.type_id)
434
+ yield GraphEdge("DEPENDS_ON", from_label, {"id": from_id}, target.kind, {"id": target.type_id})
435
+
436
+
437
+ def _pick(candidates: list[tuple[str, str, str, str]]) -> str:
438
+ return sorted(candidates, key=lambda c: c[1])[0][1]
439
+
440
+
441
+ def _pick_method(candidates: list[tuple[str, str, str, str]], e: _Entry) -> str:
442
+ """Method analog of _resolve_target's module/package bias: a `(owner_id, method_id, package,
443
+ module)` candidate from the referrer's own module+package wins, then same-package, then
444
+ same-module, then anywhere -- keeps two modules' same-named, same-package methods from cross-binding."""
445
+ same_mod_pkg = [c for c in candidates if c[3] == e.module and c[2] == e.package]
446
+ same_pkg = [c for c in candidates if c[2] == e.package]
447
+ same_mod = [c for c in candidates if c[3] == e.module]
448
+ return _pick(same_mod_pkg or same_pkg or same_mod or candidates)
449
+
450
+
451
+ def _resolve_call(call: RawCall, e: _Entry, member_types: dict[str, str], imports: dict[str, str],
452
+ type_index: dict[str, list[_Entry]], method_index: dict[str, list[tuple[str, str, str, str]]]):
453
+ """Resolve one call to one of:
454
+ * ``("local", target_method_id, extra_props)`` -- binds to a project Method (as before);
455
+ * ``("extern", _Extern)`` -- a callee we can NAME but that isn't defined here (a JDK/stdlib
456
+ or other-repo method) -> a placeholder, ADR 0004;
457
+ * ``None`` -- a callee we genuinely can't name (a bare/inherited call), or an intra-project
458
+ dangling reference (a missing member of a *project* type -- deliberately left dropped, so
459
+ an incremental resync leaves no stale `extern://` behind).
460
+
461
+ `new X()` -> X's constructor; a receiver naming a known field prefers that field's type's
462
+ method; a bare / `this` call prefers the same type, then same package, then anywhere."""
463
+ if call.is_new:
464
+ target = _resolve_target(call.name, type_index, e.package, e.module)
465
+ if target is not None:
466
+ ctor = next((m for m in target.raw_type.methods if m.kind == "CONSTRUCTOR"), None)
467
+ if ctor is not None:
468
+ return "local", _method_id(target.type_id, ctor), {}
469
+ if target.seed_ctor_id: # a NON-emit target: its constructor id came from the graph seed
470
+ return "local", target.seed_ctor_id, {}
471
+ return None # a project type's implicit/absent constructor -> intra-project, drop
472
+ # `new` of a type not in this project -> external constructor (member = the type's name).
473
+ return _extern_result(call.name, call.name, imports, receiver_type=None)
474
+
475
+ candidates = method_index.get(call.name)
476
+ if not candidates:
477
+ # No project method of this name -> external if we can name the receiver's owning type.
478
+ return _extern_call(call, e, member_types, imports, type_index)
479
+
480
+ if call.receiver is not None and call.receiver != "this":
481
+ rtype = member_types.get(call.receiver)
482
+ if rtype is not None:
483
+ resolved_project = False
484
+ for type_name in _referenced_names(rtype):
485
+ target_type = _resolve_target(type_name, type_index, e.package, e.module)
486
+ if target_type is None:
487
+ continue
488
+ resolved_project = True
489
+ matches = [c for c in candidates if c[0] == target_type.type_id]
490
+ if matches:
491
+ return "local", _pick(matches), {"receiver_type": target_type.name}
492
+ if resolved_project:
493
+ return None # receiver is a project type, but missing this member -> intra-project
494
+ # receiver's type is external -> name the call on that type (ADR 0004).
495
+ head = next(iter(_referenced_names(rtype)), None)
496
+ return _extern_result(head, call.name, imports, receiver_type=head) if head else None
497
+ return "local", _pick_method(candidates, e), {}
498
+
499
+ same_type = [c for c in candidates if c[0] == e.type_id] # same-module already (type_id is module-scoped)
500
+ if same_type:
501
+ return "local", _pick(same_type), {}
502
+ return "local", _pick_method(candidates, e), {}
503
+
504
+
505
+ def _extern_call(call: RawCall, e: _Entry, member_types: dict[str, str], imports: dict[str, str],
506
+ type_index: dict[str, list[_Entry]]):
507
+ """A call with no project method of its name -> a placeholder when we can name the owning type
508
+ (a field receiver's declared type, or a static `Type.method` receiver), else ``None`` (a bare
509
+ `foo()` / `this.foo()` / a chained receiver: the owner is unknowable, so skip). A receiver that
510
+ resolves to a *project* type is intra-project dangling -> dropped (GUARD, ADR 0004)."""
511
+ recv = call.receiver
512
+ if recv is None or recv == "this":
513
+ return None # unqualified / inherited call -- can't name the owning type
514
+ rtype = member_types.get(recv)
515
+ if rtype is not None: # receiver is a field -> its declared type owns the method
516
+ head = next(iter(_referenced_names(rtype)), None)
517
+ if head is None:
518
+ return None
519
+ if _resolve_target(head, type_index, e.package, e.module) is not None:
520
+ return None # project type missing the member -> intra-project dangling, drop
521
+ return _extern_result(head, call.name, imports, receiver_type=head)
522
+ # A bare identifier receiver that isn't a field: a static `Type.method` call when it names a
523
+ # type (import-bound, a known java.lang type, or capitalized per Java convention).
524
+ if _resolve_target(recv, type_index, e.package, e.module) is not None:
525
+ return None # static call on a PROJECT type missing the member -> intra-project, drop
526
+ if recv in imports or recv in _JAVA_LANG or recv[:1].isupper():
527
+ return _extern_result(recv, call.name, imports, receiver_type=recv)
528
+ return None # a local variable of unknown type -- can't name the owning type
529
+
530
+
531
+ def _extern_result(type_simple: str, member: str, imports: dict[str, str], receiver_type: str | None):
532
+ """Build the `("extern", _Extern)` result for a call on `type_simple.member` -- resolving the
533
+ type's fqcn from this file's imports so the linkage key matches the real definition's."""
534
+ fqcn = _fqcn(type_simple, imports)
535
+ qualified = f"{fqcn}#{member}"
536
+ return "extern", _Extern(
537
+ linkage=ids.extern_method_key(qualified),
538
+ name=member,
539
+ qualified=qualified,
540
+ origin=_origin(fqcn),
541
+ receiver_type=receiver_type,
542
+ )
543
+
544
+
545
+ def _emit_calls(e: _Entry, type_index: dict[str, list[_Entry]], method_index: dict[str, list[tuple[str, str, str, str]]],
546
+ imports: dict[str, str], emitted_externs: set[str]) -> Iterator[GraphNode | GraphEdge]:
547
+ member_types = {f.name: f.type for f in e.raw_type.fields if f.type}
548
+ for m in e.raw_type.methods:
549
+ mid = _method_id(e.type_id, m)
550
+ emitted: set[str] = set() # dedup CALLS targets from this method (project id or placeholder id)
551
+ for call in m.calls:
552
+ hit = _resolve_call(call, e, member_types, imports, type_index, method_index)
553
+ if hit is None:
554
+ continue
555
+ if hit[0] == "local":
556
+ _, target_id, extra = hit
557
+ if target_id in emitted:
558
+ continue
559
+ emitted.add(target_id)
560
+ yield GraphEdge("CALLS", "Method", {"id": mid}, "Method", {"id": target_id}, {"resolution": "name", **extra})
561
+ else: # ("extern", _Extern): a placeholder Method reached by an ordinary CALLS edge (ADR 0004)
562
+ ext = hit[1]
563
+ if ext.linkage in emitted:
564
+ continue
565
+ emitted.add(ext.linkage)
566
+ if ext.linkage not in emitted_externs:
567
+ emitted_externs.add(ext.linkage)
568
+ yield _external_method_node(ext)
569
+ props = {"resolution": "external"}
570
+ if ext.receiver_type is not None:
571
+ props["receiver_type"] = ext.receiver_type
572
+ yield GraphEdge("CALLS", "Method", {"id": mid}, "Method", {"id": ext.linkage}, props)
573
+
574
+
575
+ # -- helpers -------------------------------------------------------------------------------
576
+
577
+ def _import_index(rf: RawFile) -> dict[str, str]:
578
+ """Map a simple type name to its fqcn from this file's single-type imports, so a call on an
579
+ external/JDK receiver can be named by its real fqcn (ADR 0004). Wildcard/static imports carry
580
+ no simple-name -> fqcn mapping, so they're skipped; a plain (non-static) type import wins."""
581
+ idx: dict[str, str] = {}
582
+ for imp in rf.imports:
583
+ if imp.is_wildcard or imp.is_static:
584
+ continue
585
+ idx.setdefault(imp.name.rsplit(".", 1)[-1], imp.name)
586
+ return idx
587
+
588
+
589
+ def _fqcn(simple: str, imports: dict[str, str]) -> str:
590
+ """Resolve a simple type name to its fully-qualified name via this file's imports, falling back
591
+ to `java.lang` for the implicit types, else the bare simple name (still a stable linkage key)."""
592
+ if simple in imports:
593
+ return imports[simple]
594
+ if simple in _JAVA_LANG:
595
+ return f"java.lang.{simple}"
596
+ return simple
597
+
598
+
599
+ def _type_fqcn(e: _Entry) -> str:
600
+ """The type's fully-qualified name (matching its node's `qualified_name`), used as the owner
601
+ portion of a real method's cross-repo linkage key."""
602
+ return f"{e.package}.{e.name}" if e.package else e.name
603
+
604
+
605
+ def _external_method_node(ext: _Extern) -> GraphNode:
606
+ """A placeholder for an unresolved call, keyed by its cross-repo linkage so a later ingest of
607
+ the defining repo takes it over (ADR 0004). Shallow: shape mirrors a real Method so the same
608
+ CALLS queries reach it; `resolved:false` + `origin` mark it."""
609
+ return GraphNode("Method", {"id": ext.linkage}, {
610
+ "name": ext.name, "qualified_name": ext.qualified, "resolved": False,
611
+ "origin": ext.origin, "linkage_key": ext.linkage,
612
+ })
613
+
614
+
615
+ def _norm(path: str) -> str:
616
+ return path.replace("\\", "/").lstrip("./")
617
+
618
+
619
+ def _basename(path: str) -> str:
620
+ return _norm(path).rsplit("/", 1)[-1]