auryn-php 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,133 @@
1
+ """Picklable dataclasses produced by file_parser (phase-1, per-file, no shared state -- safe
2
+ under a ProcessPoolExecutor). No tree-sitter node ever crosses this boundary; resolution.py
3
+ turns these into graph nodes/edges once every file has been parsed.
4
+
5
+ Everything here is what a single tree-sitter parse of one .php file can know on its own -- names,
6
+ types-as-written (text), visibility/modifiers, call *names* + receivers. Cross-file decisions
7
+ (does this call resolve to a project method/function? does a base name name a project type?) are
8
+ made later, in resolution.py, where all files are visible at once.
9
+
10
+ Modelled after the Java ingestor's raw_model (PHP is a structural sibling: explicit classes/
11
+ interfaces with extends/implements), extended for PHP's own constructs: `Trait` types and the
12
+ `use TraitName;` uses list (USES_TRAIT), `Property` members with a visibility (PHP's term, matching
13
+ the C# precedent), class `Constant`s, `EnumCase`s, top-level free `Function`s, and
14
+ constructor-promoted properties. A class has a single `superclass` plus a separate `interfaces`
15
+ list, so EXTENDS vs IMPLEMENTS needs no naming heuristic. line_start/line_end are 1-based
16
+ inclusive; 0 means not captured."""
17
+
18
+ from __future__ import annotations
19
+
20
+ from dataclasses import dataclass, field
21
+
22
+
23
+ @dataclass
24
+ class RawParameter:
25
+ name: str # without the leading `$`
26
+ type: str # type as written, e.g. "Store", "?Store", "int|string", ""
27
+ position: int
28
+ is_variadic: bool = False # `Type ...$args`
29
+ is_promoted: bool = False # constructor property promotion (also becomes a Property)
30
+ visibility: str = "" # set only for promoted params ("public"/"private"/"protected")
31
+
32
+
33
+ @dataclass
34
+ class RawCall:
35
+ name: str # the callee's simple name (method/function name, or the created type)
36
+ receiver: str | None = None
37
+ """The receiver as a simple name: "this" for `$this->m()`; a property/var name for
38
+ `$this->store->m()` ("store") or `$store->m()` ("store"); a class name for `Foo::m()`
39
+ ("Foo") or one of "self"/"static"/"parent". None for a bare `foo()` or a receiver too
40
+ complex to name. resolution.py uses it to prefer a receiver's declared type."""
41
+ kind: str = "function" # "function" | "method" | "static" | "new"
42
+
43
+
44
+ @dataclass
45
+ class RawMethod:
46
+ name: str
47
+ kind: str # "ORDINARY" | "CONSTRUCTOR"
48
+ visibility: str # "public" | "private" | "protected" (PHP default: public)
49
+ is_static: bool = False
50
+ is_abstract: bool = False
51
+ is_final: bool = False
52
+ return_type: str | None = None
53
+ parameters: list[RawParameter] = field(default_factory=list)
54
+ calls: list[RawCall] = field(default_factory=list)
55
+ source: str = ""
56
+ doc: str = "" # shared `doc` property: the leading comment above the declaration, cleaned
57
+ line_start: int = 0
58
+ line_end: int = 0
59
+
60
+
61
+ @dataclass
62
+ class RawFunction: # top-level (free) function
63
+ name: str
64
+ return_type: str | None = None
65
+ parameters: list[RawParameter] = field(default_factory=list)
66
+ calls: list[RawCall] = field(default_factory=list)
67
+ source: str = ""
68
+ doc: str = "" # shared `doc` property: the leading comment above the declaration, cleaned
69
+ line_start: int = 0
70
+ line_end: int = 0
71
+
72
+
73
+ @dataclass
74
+ class RawProperty:
75
+ name: str # without the leading `$`
76
+ type: str
77
+ visibility: str = "public"
78
+ is_static: bool = False
79
+ is_readonly: bool = False
80
+ is_promoted: bool = False # declared via constructor property promotion
81
+ line_start: int = 0
82
+ line_end: int = 0
83
+
84
+
85
+ @dataclass
86
+ class RawConstant:
87
+ name: str
88
+ visibility: str = "public"
89
+ value: str = "" # value text as written
90
+ line_start: int = 0
91
+ line_end: int = 0
92
+
93
+
94
+ @dataclass
95
+ class RawEnumCase:
96
+ name: str
97
+ value: str = "" # backing value text ("" for pure enums)
98
+
99
+
100
+ @dataclass
101
+ class RawType:
102
+ kind: str # "Class" | "Interface" | "Trait" | "Enum"
103
+ name: str
104
+ namespace: str # "" for the global namespace; backslash-separated otherwise ("App\\Models")
105
+ is_abstract: bool = False
106
+ is_final: bool = False
107
+ superclass: str | None = None # class only -- single base (simple name)
108
+ interfaces: list[str] = field(default_factory=list) # implemented (class/enum) or extended (interface)
109
+ traits: list[str] = field(default_factory=list) # `use TraitName;` in the body -> USES_TRAIT
110
+ backing_type: str | None = None # enum backing type ("string"/"int") if any
111
+ methods: list[RawMethod] = field(default_factory=list)
112
+ properties: list[RawProperty] = field(default_factory=list)
113
+ constants: list[RawConstant] = field(default_factory=list)
114
+ enum_cases: list[RawEnumCase] = field(default_factory=list)
115
+ source: str = ""
116
+ doc: str = "" # shared `doc` property: the leading comment above the declaration, cleaned
117
+ line_start: int = 0
118
+ line_end: int = 0
119
+
120
+
121
+ @dataclass
122
+ class RawUse: # a top-level `use` import
123
+ name: str # imported fully-qualified name, e.g. "App\\Contracts\\Repository"
124
+ alias: str | None = None # `use X as Y` -> "Y"
125
+
126
+
127
+ @dataclass
128
+ class RawFile:
129
+ path: str
130
+ namespace: str = ""
131
+ uses: list[RawUse] = field(default_factory=list)
132
+ types: list[RawType] = field(default_factory=list)
133
+ functions: list[RawFunction] = field(default_factory=list)
@@ -0,0 +1,519 @@
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 namespace tier, resolving
3
+ EXTENDS/IMPLEMENTS/USES_TRAIT and parameter/return/property type references to project types, and
4
+ best-effort call resolution.
5
+
6
+ Adapted from the Java ingestor's resolution (PHP is its structural sibling: explicit classes/
7
+ interfaces with extends/implements), extended for PHP: the tier is `Namespace` (backslash-
8
+ separated); there is a `Trait` type kind and a `USES_TRAIT` edge; class `Property`/`Constant`
9
+ members and enum `EnumCase`s; and top-level free `Function`s (indexed so a bare `foo()` resolves,
10
+ Python/C-style) alongside methods.
11
+
12
+ Name-based only -- this is the fast tree-sitter engine, so every CALLS edge is stamped
13
+ `resolution="name"`. Full PHP name-resolution (use-statement aliasing, autoloading/PSR-4,
14
+ trait-flattened and inherited-member call targets) is the deferred deep pass; a future deep engine
15
+ would re-emit the same node ids with a stronger provenance (the two-phase model). An ambiguous
16
+ call still produces no edge rather than a wrong guess, but a *nameable* unresolved call (a
17
+ builtin, a vendor/other-repo callable, or a not-yet-ingested sibling repo's symbol) becomes a
18
+ first-class placeholder node reached by an ordinary CALLS edge, keyed by its cross-repo
19
+ `linkage_key` so it heals to the real definition when that repo joins the graph (ADR 0004)."""
20
+
21
+ from __future__ import annotations
22
+
23
+ import re
24
+ from collections import defaultdict
25
+ from collections.abc import Iterator
26
+ from dataclasses import dataclass
27
+
28
+ from auryn.core.graph_model import GraphEdge, GraphNode
29
+ from auryn.ingestors.php import ids
30
+ from auryn.ingestors.php.raw_model import RawFile, RawFunction, RawMethod, RawType
31
+
32
+ _IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
33
+ # Type tokens that never name a project type -- PHP built-in types/keywords in type text.
34
+ _NON_TYPE_TOKENS = frozenset(
35
+ {"int", "integer", "float", "double", "string", "bool", "boolean", "void", "array",
36
+ "object", "mixed", "callable", "iterable", "null", "false", "true", "never", "self",
37
+ "static", "parent", "this"}
38
+ )
39
+
40
+ # ADR 0004: a best-effort set of common PHP built-in functions, so a bare call to one is surfaced
41
+ # with origin="builtin" (a terminal external that never resolves to an ingested repo) rather than
42
+ # "external" (a candidate a sibling repo could define). Not exhaustive -- the fast engine can't
43
+ # know the full internal-function list; a future deep pass would refine it.
44
+ _PHP_BUILTINS = frozenset(
45
+ {"strlen", "str_replace", "count", "array_map", "array_filter", "implode", "explode",
46
+ "json_encode", "json_decode", "isset", "printf", "sprintf", "preg_match", "in_array",
47
+ "array_keys", "array_values"}
48
+ )
49
+
50
+
51
+ @dataclass
52
+ class _Entry:
53
+ type_id: str
54
+ kind: str # "Class" | "Interface" | "Trait" | "Enum"
55
+ name: str
56
+ namespace: str
57
+ raw_type: RawType
58
+ file_id: str
59
+ scope_id: str
60
+ scope_label: str # "Namespace" | "Project"
61
+
62
+
63
+ @dataclass
64
+ class _FuncEntry:
65
+ func_id: str
66
+ name: str
67
+ namespace: str
68
+ raw_func: RawFunction
69
+ file_id: str
70
+ scope_id: str
71
+ scope_label: str # "Namespace" | "Project"
72
+
73
+
74
+ def resolve(raw_files: list[RawFile], project_id: str) -> Iterator[GraphNode | GraphEdge]:
75
+ file_ids: dict[str, str] = {}
76
+ namespaces_seen: set[str] = set()
77
+ for rf in raw_files:
78
+ fid = ids.file_id(project_id, rf.path)
79
+ file_ids[rf.path] = fid
80
+ yield GraphNode("File", {"id": fid}, {"name": _basename(rf.path), "path": _norm(rf.path)})
81
+ yield GraphEdge("HAS_FILE", "Project", {"id": project_id}, "File", {"id": fid})
82
+ for rt in rf.types:
83
+ if rt.namespace:
84
+ namespaces_seen.add(rt.namespace)
85
+ for fn in rf.functions:
86
+ if rf.namespace:
87
+ namespaces_seen.add(rf.namespace)
88
+ yield from _emit_namespaces(namespaces_seen, project_id)
89
+
90
+ entries: list[_Entry] = []
91
+ func_entries: list[_FuncEntry] = []
92
+ for rf in raw_files:
93
+ for rt in rf.types:
94
+ scope_id, scope_label = _scope(project_id, rt.namespace)
95
+ entries.append(_Entry(
96
+ ids.type_id(scope_id, rt.kind, rt.name), rt.kind, rt.name, rt.namespace, rt,
97
+ file_ids[rf.path], scope_id, scope_label,
98
+ ))
99
+ for fn in rf.functions:
100
+ scope_id, scope_label = _scope(project_id, rf.namespace)
101
+ func_entries.append(_FuncEntry(
102
+ ids.function_id(scope_id, fn.name, [p.type for p in fn.parameters]),
103
+ fn.name, rf.namespace, fn, file_ids[rf.path], scope_id, scope_label,
104
+ ))
105
+
106
+ type_index: dict[str, list[_Entry]] = defaultdict(list)
107
+ for e in entries:
108
+ type_index[e.name].append(e)
109
+
110
+ method_index: dict[str, list[tuple[str, str, str]]] = defaultdict(list)
111
+ for e in entries:
112
+ for m in e.raw_type.methods:
113
+ method_index[m.name].append((e.type_id, _method_id(e.type_id, m), e.namespace))
114
+
115
+ function_index: dict[str, list[tuple[str, str]]] = defaultdict(list)
116
+ for fe in func_entries:
117
+ function_index[fe.name].append((fe.func_id, fe.namespace))
118
+
119
+ # Pass 1: nodes + structural edges (so pass 2's cross-refs always have a landing node).
120
+ for e in entries:
121
+ yield from _emit_type_and_members(e)
122
+ for fe in func_entries:
123
+ yield from _emit_function(fe)
124
+ # Pass 2: cross-references. `emitted_externs` dedups placeholder nodes across the whole pass
125
+ # (ADR 0004) so every caller of the same missing symbol MERGEs onto one node.
126
+ emitted_externs: set[str] = set()
127
+ for e in entries:
128
+ yield from _emit_hierarchy(e, type_index)
129
+ yield from _emit_type_references(e, type_index)
130
+ yield from _emit_calls(e, type_index, method_index, function_index, emitted_externs)
131
+ for fe in func_entries:
132
+ yield from _emit_function_references(fe, type_index)
133
+ yield from _emit_function_calls(fe, type_index, method_index, function_index, emitted_externs)
134
+
135
+
136
+ # -- scope / namespaces --------------------------------------------------------------------
137
+
138
+ def _scope(project_id: str, namespace: str) -> tuple[str, str]:
139
+ if namespace:
140
+ return ids.namespace_id(project_id, namespace), "Namespace"
141
+ return project_id, "Project"
142
+
143
+
144
+ def _emit_namespaces(namespaces: set[str], project_id: str) -> Iterator[GraphNode | GraphEdge]:
145
+ """Materialize every prefix of every declared namespace as a Namespace node (as C#/Java do):
146
+ the first segment hangs off the Project via HAS_NAMESPACE, deeper segments chain via
147
+ HAS_SUBNAMESPACE. `App\\Models` -> Namespace(App) -> Namespace(App\\Models)."""
148
+ emitted: set[str] = set()
149
+ for namespace in namespaces:
150
+ prefix = ""
151
+ parent_id, parent_label, parent_rel = project_id, "Project", "HAS_NAMESPACE"
152
+ for segment in namespace.split("\\"):
153
+ prefix = f"{prefix}\\{segment}" if prefix else segment
154
+ nid = ids.namespace_id(project_id, prefix)
155
+ if nid not in emitted:
156
+ emitted.add(nid)
157
+ yield GraphNode("Namespace", {"id": nid}, {"name": segment, "qualified_name": prefix})
158
+ yield GraphEdge(parent_rel, parent_label, {"id": parent_id}, "Namespace", {"id": nid})
159
+ parent_id, parent_label, parent_rel = nid, "Namespace", "HAS_SUBNAMESPACE"
160
+
161
+
162
+ # -- pass 1: nodes + structural edges ------------------------------------------------------
163
+
164
+ def _type_properties(rt: RawType) -> dict:
165
+ props: dict = {
166
+ "name": rt.name,
167
+ "qualified_name": f"{rt.namespace}\\{rt.name}" if rt.namespace else rt.name,
168
+ "namespace": rt.namespace,
169
+ "source": rt.source,
170
+ "doc": rt.doc,
171
+ "line_start": rt.line_start,
172
+ "line_end": rt.line_end,
173
+ }
174
+ if rt.kind == "Class":
175
+ props.update(is_abstract=rt.is_abstract, is_final=rt.is_final)
176
+ elif rt.kind == "Enum":
177
+ props["backing_type"] = rt.backing_type
178
+ return props
179
+
180
+
181
+ def _emit_type_and_members(e: _Entry) -> Iterator[GraphNode | GraphEdge]:
182
+ yield GraphNode(e.kind, {"id": e.type_id}, _type_properties(e.raw_type))
183
+ yield GraphEdge("HAS_TYPE", e.scope_label, {"id": e.scope_id}, e.kind, {"id": e.type_id})
184
+ yield GraphEdge("DEFINED_IN", e.kind, {"id": e.type_id}, "File", {"id": e.file_id})
185
+
186
+ type_qname = f"{e.namespace}\\{e.raw_type.name}" if e.namespace else e.raw_type.name
187
+ for m in e.raw_type.methods:
188
+ yield from _emit_method(e.type_id, e.kind, type_qname, m)
189
+ for p in e.raw_type.properties:
190
+ yield from _emit_property(e.type_id, e.kind, p)
191
+ for k in e.raw_type.constants:
192
+ cid = ids.constant_id(e.type_id, k.name)
193
+ yield GraphNode("Constant", {"id": cid}, {"name": k.name, "value": k.value, "visibility": k.visibility})
194
+ yield GraphEdge("HAS_CONSTANT", e.kind, {"id": e.type_id}, "Constant", {"id": cid})
195
+ for case in e.raw_type.enum_cases:
196
+ caseid = ids.enum_case_id(e.type_id, case.name)
197
+ yield GraphNode("EnumCase", {"id": caseid}, {"name": case.name, "value": case.value})
198
+ yield GraphEdge("HAS_ENUM_CASE", "Enum", {"id": e.type_id}, "EnumCase", {"id": caseid})
199
+
200
+
201
+ def _method_id(type_id: str, m: RawMethod) -> str:
202
+ return ids.method_id(type_id, m.name, [p.type for p in m.parameters])
203
+
204
+
205
+ def _emit_method(type_id: str, type_label: str, type_qname: str, m: RawMethod) -> Iterator[GraphNode | GraphEdge]:
206
+ mid = _method_id(type_id, m)
207
+ yield GraphNode("Method", {"id": mid}, {
208
+ "name": m.name,
209
+ "kind": m.kind,
210
+ "visibility": m.visibility,
211
+ "is_static": m.is_static,
212
+ "is_abstract": m.is_abstract,
213
+ "is_final": m.is_final,
214
+ "return_type": m.return_type,
215
+ "source": m.source,
216
+ "doc": m.doc,
217
+ "line_start": m.line_start,
218
+ "line_end": m.line_end,
219
+ # Cross-repo key (ADR 0004): the name a consumer writes -- `App\\Billing::charge`.
220
+ "linkage_key": ids.extern_function_key(f"{type_qname}::{m.name}"),
221
+ })
222
+ yield GraphEdge("HAS_METHOD", type_label, {"id": type_id}, "Method", {"id": mid})
223
+ for i, p in enumerate(m.parameters):
224
+ yield from _emit_parameter(mid, "Method", p, i)
225
+
226
+
227
+ def _emit_function(fe: _FuncEntry) -> Iterator[GraphNode | GraphEdge]:
228
+ fn = fe.raw_func
229
+ qualified = f"{fe.namespace}\\{fn.name}" if fe.namespace else fn.name
230
+ yield GraphNode("Function", {"id": fe.func_id}, {
231
+ "name": fn.name,
232
+ "qualified_name": qualified,
233
+ "return_type": fn.return_type,
234
+ "source": fn.source,
235
+ "doc": fn.doc,
236
+ "line_start": fn.line_start,
237
+ "line_end": fn.line_end,
238
+ # Cross-repo key (ADR 0004): the name a consumer writes -- `App\\helper` / `helper`.
239
+ "linkage_key": ids.extern_function_key(qualified),
240
+ })
241
+ yield GraphEdge("HAS_FUNCTION", fe.scope_label, {"id": fe.scope_id}, "Function", {"id": fe.func_id})
242
+ yield GraphEdge("DEFINED_IN", "Function", {"id": fe.func_id}, "File", {"id": fe.file_id})
243
+ for i, p in enumerate(fn.parameters):
244
+ yield from _emit_parameter(fe.func_id, "Function", p, i)
245
+
246
+
247
+ def _emit_parameter(parent_id: str, parent_label: str, param, position: int) -> Iterator[GraphNode | GraphEdge]:
248
+ pid = ids.parameter_id(parent_id, position, param.name)
249
+ yield GraphNode("Parameter", {"id": pid}, {
250
+ "name": param.name, "type": param.type, "position": param.position,
251
+ "is_variadic": param.is_variadic, "is_promoted": param.is_promoted,
252
+ })
253
+ yield GraphEdge("HAS_PARAMETER", parent_label, {"id": parent_id}, "Parameter", {"id": pid})
254
+
255
+
256
+ def _emit_property(type_id: str, type_label: str, p) -> Iterator[GraphNode | GraphEdge]:
257
+ pid = ids.property_id(type_id, p.name)
258
+ yield GraphNode("Property", {"id": pid}, {
259
+ "name": p.name, "type": p.type, "visibility": p.visibility,
260
+ "is_static": p.is_static, "is_readonly": p.is_readonly, "is_promoted": p.is_promoted,
261
+ })
262
+ yield GraphEdge("HAS_PROPERTY", type_label, {"id": type_id}, "Property", {"id": pid})
263
+
264
+
265
+ # -- pass 2: hierarchy, type references, calls ---------------------------------------------
266
+
267
+ def _resolve_target(name: str, type_index: dict[str, list[_Entry]], from_namespace: str) -> _Entry | None:
268
+ matches = type_index.get(name)
269
+ if not matches:
270
+ return None
271
+ same_ns = [m for m in matches if m.namespace == from_namespace]
272
+ pool = same_ns or matches
273
+ return sorted(pool, key=lambda m: m.type_id)[0] # deterministic on ambiguity
274
+
275
+
276
+ def _emit_hierarchy(e: _Entry, type_index: dict[str, list[_Entry]]) -> Iterator[GraphEdge]:
277
+ rt = e.raw_type
278
+ if rt.superclass: # class -> class
279
+ target = _resolve_target(rt.superclass, type_index, e.namespace)
280
+ if target is not None and target.type_id != e.type_id:
281
+ yield GraphEdge("EXTENDS", e.kind, {"id": e.type_id}, target.kind, {"id": target.type_id})
282
+ for iface in rt.interfaces:
283
+ target = _resolve_target(iface, type_index, e.namespace)
284
+ if target is None or target.type_id == e.type_id:
285
+ continue
286
+ # an interface's `interfaces` list is really its super-interfaces -> EXTENDS.
287
+ rel = "EXTENDS" if e.kind == "Interface" else "IMPLEMENTS"
288
+ yield GraphEdge(rel, e.kind, {"id": e.type_id}, target.kind, {"id": target.type_id})
289
+ for trait in rt.traits:
290
+ target = _resolve_target(trait, type_index, e.namespace)
291
+ if target is not None and target.type_id != e.type_id:
292
+ yield GraphEdge("USES_TRAIT", e.kind, {"id": e.type_id}, target.kind, {"id": target.type_id})
293
+
294
+
295
+ def _referenced_names(type_text: str | None) -> list[str]:
296
+ if not type_text:
297
+ return []
298
+ return [n for n in _IDENTIFIER_RE.findall(type_text) if n not in _NON_TYPE_TOKENS]
299
+
300
+
301
+ def _emit_type_references(e: _Entry, type_index: dict[str, list[_Entry]]) -> Iterator[GraphEdge]:
302
+ for m in e.raw_type.methods:
303
+ mid = _method_id(e.type_id, m)
304
+ names = set(_referenced_names(m.return_type))
305
+ for p in m.parameters:
306
+ names.update(_referenced_names(p.type))
307
+ yield from _depends_on("Method", mid, names, e.namespace, e.type_id, type_index)
308
+ for p in e.raw_type.properties:
309
+ pid = ids.property_id(e.type_id, p.name)
310
+ yield from _depends_on("Property", pid, set(_referenced_names(p.type)), e.namespace, e.type_id, type_index)
311
+
312
+
313
+ def _emit_function_references(fe: _FuncEntry, type_index: dict[str, list[_Entry]]) -> Iterator[GraphEdge]:
314
+ fn = fe.raw_func
315
+ names = set(_referenced_names(fn.return_type))
316
+ for p in fn.parameters:
317
+ names.update(_referenced_names(p.type))
318
+ yield from _depends_on("Function", fe.func_id, names, fe.namespace, None, type_index)
319
+
320
+
321
+ def _depends_on(from_label: str, from_id: str, names: set[str], from_namespace: str,
322
+ self_type_id: str | None, type_index) -> Iterator[GraphEdge]:
323
+ emitted: set[str] = set()
324
+ for name in names:
325
+ target = _resolve_target(name, type_index, from_namespace)
326
+ if target is None or target.type_id == self_type_id or target.type_id in emitted:
327
+ continue
328
+ emitted.add(target.type_id)
329
+ yield GraphEdge("DEPENDS_ON", from_label, {"id": from_id}, target.kind, {"id": target.type_id})
330
+
331
+
332
+ def _pick(candidates: list[tuple[str, str, str]]) -> str:
333
+ return sorted(candidates, key=lambda c: c[1])[0][1]
334
+
335
+
336
+ def _same_type_then_ns(cands, from_type_id: str | None, from_namespace: str):
337
+ if from_type_id is not None:
338
+ same_type = [c for c in cands if c[0] == from_type_id]
339
+ if same_type:
340
+ return "Method", _pick(same_type), {}
341
+ same_ns = [c for c in cands if c[2] == from_namespace]
342
+ return "Method", _pick(same_ns or cands), {}
343
+
344
+
345
+ def _resolve_call(call, from_type_id: str | None, from_namespace: str, receiver_types: dict[str, str],
346
+ type_index, method_index, function_index):
347
+ """(target_label, target_id, extra_props) or None.
348
+
349
+ `new X()` -> X's `__construct`; a bare `foo()` -> a project Function (same-namespace first);
350
+ `$this->m()`/`self::m()` -> the same type, then same namespace; a receiver naming a known
351
+ property/param prefers that declared type's method; `Foo::m()` -> Foo's method directly."""
352
+ if call.kind == "new":
353
+ target = _resolve_target(call.name, type_index, from_namespace)
354
+ if target is not None:
355
+ ctor = next((m for m in target.raw_type.methods if m.kind == "CONSTRUCTOR"), None)
356
+ if ctor is not None:
357
+ return "Method", _method_id(target.type_id, ctor), {}
358
+ return None
359
+
360
+ if call.kind == "function":
361
+ cands = function_index.get(call.name)
362
+ if not cands:
363
+ return None
364
+ same_ns = [c for c in cands if c[1] == from_namespace]
365
+ return "Function", sorted(same_ns or cands, key=lambda c: c[0])[0][0], {}
366
+
367
+ cands = method_index.get(call.name)
368
+ if not cands:
369
+ return None
370
+
371
+ if call.kind == "static":
372
+ recv = call.receiver
373
+ if recv in (None, "self", "static", "parent"):
374
+ return _same_type_then_ns(cands, from_type_id, from_namespace)
375
+ target_type = _resolve_target(recv, type_index, from_namespace)
376
+ if target_type is not None:
377
+ matches = [c for c in cands if c[0] == target_type.type_id]
378
+ if matches:
379
+ return "Method", _pick(matches), {"receiver_type": target_type.name}
380
+ return None
381
+
382
+ # instance (member) call
383
+ recv = call.receiver
384
+ if recv in (None, "this"):
385
+ return _same_type_then_ns(cands, from_type_id, from_namespace)
386
+ rtype = receiver_types.get(recv)
387
+ if rtype is not None:
388
+ for type_name in _referenced_names(rtype):
389
+ target_type = _resolve_target(type_name, type_index, from_namespace)
390
+ if target_type is None:
391
+ continue
392
+ matches = [c for c in cands if c[0] == target_type.type_id]
393
+ if matches:
394
+ return "Method", _pick(matches), {"receiver_type": target_type.name}
395
+ return None # resolved the receiver's type, but it has no such method
396
+ same_ns = [c for c in cands if c[2] == from_namespace] # unknown local var -> name-based guess
397
+ return "Method", _pick(same_ns or cands), {}
398
+
399
+
400
+ def _emit_callable_calls(from_label, from_id, from_type_id, from_namespace, calls, receiver_types,
401
+ type_index, method_index, function_index, emitted_externs) -> Iterator[GraphNode | GraphEdge]:
402
+ emitted: set[str] = set()
403
+ for call in calls:
404
+ hit = _resolve_call(call, from_type_id, from_namespace, receiver_types, type_index, method_index, function_index)
405
+ if hit is not None:
406
+ target_label, target_id, extra = hit
407
+ if target_id in emitted:
408
+ continue
409
+ emitted.add(target_id)
410
+ yield GraphEdge("CALLS", from_label, {"id": from_id}, target_label, {"id": target_id}, {"resolution": "name", **extra})
411
+ continue
412
+ # Unresolved (ADR 0004): a PHP built-in, a vendor/other-repo callable, or a sibling repo's
413
+ # symbol not yet ingested. When it's nameable, surface a placeholder reached by an ordinary
414
+ # CALLS edge so the reference exists in the graph and heals when the definer is ingested;
415
+ # dynamic/unknown-receiver and intra-project-dangling calls stay dropped.
416
+ ext = _external_placeholder(call, from_namespace, receiver_types, type_index)
417
+ if ext is None:
418
+ continue
419
+ label, qualified, short, origin = ext
420
+ eid = ids.extern_function_key(qualified)
421
+ if eid in emitted:
422
+ continue
423
+ emitted.add(eid)
424
+ if eid not in emitted_externs: # one placeholder node per missing symbol; edges per caller
425
+ emitted_externs.add(eid)
426
+ yield GraphNode(label, {"id": eid}, {
427
+ "name": short, "qualified_name": qualified,
428
+ "resolved": False, "origin": origin, "linkage_key": eid,
429
+ })
430
+ yield GraphEdge("CALLS", from_label, {"id": from_id}, label, {"id": eid}, {"resolution": "external"})
431
+
432
+
433
+ def _qualify_class(name_or_type: str, from_namespace: str) -> str | None:
434
+ """The cross-repo class name a consumer's receiver denotes -- so a placeholder's key lines up
435
+ with the real class's `linkage_key` (`App\\Billing`). An already-qualified reference
436
+ (`\\Vendor\\Client`, `App\\Models\\Store`) keeps its path (leading `\\` dropped); a bare name
437
+ resolves against the caller's namespace (PHP name resolution: `Billing` in `App` -> `App\\Billing`).
438
+ Union/nullable text is reduced to its first alternative. None if nothing nameable remains."""
439
+ first = name_or_type.split("|")[0].strip().lstrip("?").strip().lstrip("\\")
440
+ if not first or first in _NON_TYPE_TOKENS:
441
+ return None
442
+ if "\\" in first: # already namespace-qualified -> the path IS the FQN
443
+ return first
444
+ return f"{from_namespace}\\{first}" if from_namespace else first
445
+
446
+
447
+ def _external_placeholder(call, from_namespace: str, receiver_types: dict[str, str], type_index):
448
+ """A call that did NOT resolve to a project node -> (label, qualified_name, short_name, origin)
449
+ for a placeholder (ADR 0004), or None to leave it dropped.
450
+
451
+ Nameable -> placeholder: a free/namespaced function call (`foo()`); a `Class::method` or
452
+ `$typedvar->method()` whose receiver names a class that is NOT a project type; a
453
+ `new ExternalClass()` constructor. Dropped: self/relative/`$this` and untyped/unknown local
454
+ receivers (dynamic), and a missing member of a *project* class (intra-project dangling -- so
455
+ nothing stale survives an incremental resync). PHP namespaces are open across files/repos, so a
456
+ free function not defined here is external, never intra-project dangling. Keys are
457
+ namespace-qualified (matching the real callables' `linkage_key`) so a cross-repo call heals."""
458
+ if call.kind == "function":
459
+ if call.name in _PHP_BUILTINS: # global builtin -> terminal external, keyed by bare name
460
+ return "Function", call.name, call.name, "builtin"
461
+ qualified = f"{from_namespace}\\{call.name}" if from_namespace else call.name
462
+ return "Function", qualified, call.name, "external"
463
+
464
+ if call.kind == "new":
465
+ if _resolve_target(call.name, type_index, from_namespace) is not None:
466
+ return None # project type (ctor not modelled as an edge) -> not external
467
+ cls = _qualify_class(call.name, from_namespace)
468
+ return ("Method", f"{cls}::__construct", "__construct", "external") if cls else None
469
+
470
+ if call.kind == "static":
471
+ recv = call.receiver
472
+ if recv in (None, "self", "static", "parent"):
473
+ return None # relative/self scope -> intra-project (or dynamic)
474
+ if _resolve_target(recv, type_index, from_namespace) is not None:
475
+ return None # project class, missing method -> intra-project dangling
476
+ cls = _qualify_class(recv, from_namespace)
477
+ return ("Method", f"{cls}::{call.name}", call.name, "external") if cls else None
478
+
479
+ # instance (member) call
480
+ recv = call.receiver
481
+ if recv in (None, "this"):
482
+ return None # $this->m() unknown -> intra-project dangling
483
+ rtype = receiver_types.get(recv)
484
+ if not rtype:
485
+ return None # untyped/unknown local variable -> dynamic dispatch, unnameable
486
+ if any(_resolve_target(n, type_index, from_namespace) is not None for n in _referenced_names(rtype)):
487
+ return None # receiver typed to a PROJECT class, missing method -> intra-project dangling
488
+ cls = _qualify_class(rtype, from_namespace)
489
+ return ("Method", f"{cls}::{call.name}", call.name, "external") if cls else None
490
+
491
+
492
+ def _emit_calls(e: _Entry, type_index, method_index, function_index, emitted_externs) -> Iterator[GraphNode | GraphEdge]:
493
+ property_types = {p.name: p.type for p in e.raw_type.properties if p.type}
494
+ for m in e.raw_type.methods:
495
+ mid = _method_id(e.type_id, m)
496
+ receiver_types = {**property_types, **{p.name: p.type for p in m.parameters if p.type}}
497
+ yield from _emit_callable_calls(
498
+ "Method", mid, e.type_id, e.namespace, m.calls, receiver_types,
499
+ type_index, method_index, function_index, emitted_externs,
500
+ )
501
+
502
+
503
+ def _emit_function_calls(fe: _FuncEntry, type_index, method_index, function_index, emitted_externs) -> Iterator[GraphNode | GraphEdge]:
504
+ fn = fe.raw_func
505
+ receiver_types = {p.name: p.type for p in fn.parameters if p.type}
506
+ yield from _emit_callable_calls(
507
+ "Function", fe.func_id, None, fe.namespace, fn.calls, receiver_types,
508
+ type_index, method_index, function_index, emitted_externs,
509
+ )
510
+
511
+
512
+ # -- helpers -------------------------------------------------------------------------------
513
+
514
+ def _norm(path: str) -> str:
515
+ return path.replace("\\", "/").lstrip("./")
516
+
517
+
518
+ def _basename(path: str) -> str:
519
+ return _norm(path).rsplit("/", 1)[-1]