auryn-ruby 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,126 @@
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 .rb file can know on its own -- names,
6
+ parameter shapes, call *names* + receiver shapes, mixin/superclass names as written, `require`
7
+ targets. Cross-file decisions (does a call resolve to a project method? does a `< Base`
8
+ superclass name a project class? does a `require_relative` land on a project file?) are made
9
+ later in resolution.py, where all files are visible.
10
+
11
+ Ruby is namespace-based: a file's top level, and every `module`/`class` inside it, are scopes
12
+ that carry the same nested item lists (classes/modules/methods/consts/fields). A class and a
13
+ module both open a namespace and hold members; they differ only in that a class may have a
14
+ superclass and be instantiated. A callable is a single `RawMethod` whether free (a top-level
15
+ `def`, resolution labels it Function) or bound (a `def` inside a class/module, labelled Method).
16
+ `is_singleton` marks a class/singleton method (`def self.x`, or a `def` inside `class << self`).
17
+
18
+ Ruby is DYNAMIC: there is no static type text on a parameter, a local, or an instance variable.
19
+ So parameters carry only a `kind` (required/optional/splat/keyword/...) -- never a type -- and
20
+ call resolution is name-based (see resolution.py). line_start/line_end are 1-based inclusive."""
21
+
22
+ from __future__ import annotations
23
+
24
+ from dataclasses import dataclass, field
25
+
26
+
27
+ @dataclass
28
+ class RawParameter:
29
+ name: str
30
+ kind: str # "required"|"optional"|"splat"|"keyword"|"keyword_optional"|"hash_splat"|"block"
31
+ position: int
32
+ default: str | None = None # source text of an optional/keyword default, else None
33
+
34
+
35
+ @dataclass
36
+ class RawCall:
37
+ name: str # the callee's method name ("super" for a bare/`super(..)` call)
38
+ kind: str
39
+ """How the callee was written, driving name-based resolution in resolution.py:
40
+ "command" -- receiverless (`foo`, `foo(x)`, `foo { }`): a self-method or top-level function.
41
+ "self" -- `self.foo`: a method on the enclosing class/module.
42
+ "constant" -- `Const.foo` / `A::B.foo`: a class/module method; `qualifier` is the const path.
43
+ "instance" -- `x.foo` / `@iv.foo`: dynamic receiver; `receiver` is the local/ivar name.
44
+ "chain" -- `a.b.foo` and other complex receivers: too dynamic to name -- dropped.
45
+ "super" -- `super` / `super(..)`.
46
+ """
47
+ receiver: str | None = None # for "instance": the bare local/@ivar receiver text
48
+ qualifier: str | None = None # for "constant": the constant path as written ("A::B")
49
+
50
+
51
+ @dataclass
52
+ class RawMethod:
53
+ name: str # the method name; operator/`?`/`!`/setter (`x=`) names are kept verbatim
54
+ kind: str # "FUNCTION" (top-level def) | "METHOD" (def inside a class/module)
55
+ is_singleton: bool = False # class/singleton method (`def self.x` / `class << self` body)
56
+ visibility: str = "public" # "public" | "private" | "protected"
57
+ parameters: list[RawParameter] = field(default_factory=list)
58
+ calls: list[RawCall] = field(default_factory=list)
59
+ signature: str = "" # reconstructed `name(params)` -- the shared `signature` property
60
+ source: str = ""
61
+ doc: str = "" # shared `doc` property: the leading `#`/`=begin..=end` comment, cleaned
62
+ line_start: int = 0
63
+ line_end: int = 0
64
+
65
+
66
+ @dataclass
67
+ class RawField:
68
+ """An attribute declared via `attr_accessor`/`attr_reader`/`attr_writer` -- the closest Ruby
69
+ has to a declared field. `access` is reader/writer/accessor."""
70
+
71
+ name: str
72
+ access: str # "reader" | "writer" | "accessor"
73
+ line_start: int = 0
74
+ line_end: int = 0
75
+
76
+
77
+ @dataclass
78
+ class RawConst:
79
+ name: str # an uppercase-initial constant assignment (`MAX = 10`)
80
+ value: str = "" # the RHS source text, trimmed
81
+ line_start: int = 0
82
+ line_end: int = 0
83
+
84
+
85
+ @dataclass
86
+ class RawInclude:
87
+ name: str # the mixed-in module name as written ("Comparable", "A::B")
88
+ kind: str # "include" | "prepend" | "extend"
89
+
90
+
91
+ @dataclass
92
+ class RawModule:
93
+ name: str # the name as written (may be a `::`-qualified path, e.g. "A::B")
94
+ kind: str = "Module" # "Module" | "Class"
95
+ superclass: str | None = None # Class only: the `< Base` name as written, else None
96
+ includes: list[RawInclude] = field(default_factory=list)
97
+ methods: list[RawMethod] = field(default_factory=list)
98
+ fields: list[RawField] = field(default_factory=list)
99
+ consts: list[RawConst] = field(default_factory=list)
100
+ classes: list["RawModule"] = field(default_factory=list)
101
+ modules: list["RawModule"] = field(default_factory=list)
102
+ source: str = ""
103
+ doc: str = "" # shared `doc` property: the leading comment, cleaned
104
+ line_start: int = 0
105
+ line_end: int = 0
106
+
107
+
108
+ @dataclass
109
+ class RawRequire:
110
+ target: str # the string literal passed to require/require_relative
111
+ kind: str # "require" | "require_relative"
112
+
113
+
114
+ @dataclass
115
+ class RawFile:
116
+ """A parsed .rb file. Its own item lists are the file's top-level scope; `classes`/`modules`
117
+ hold the namespaces declared in it. Shares the item-list field names with RawModule so
118
+ file_parser's collect_scope fills either interchangeably."""
119
+
120
+ path: str
121
+ requires: list[RawRequire] = field(default_factory=list)
122
+ classes: list[RawModule] = field(default_factory=list)
123
+ modules: list[RawModule] = field(default_factory=list)
124
+ methods: list[RawMethod] = field(default_factory=list) # top-level `def` -> Function
125
+ consts: list[RawConst] = field(default_factory=list)
126
+ fields: list[RawField] = field(default_factory=list) # top-level attr_* (rare)
@@ -0,0 +1,485 @@
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 -- merging reopened namespaces (a class/module split
3
+ across files is one node), materializing the class/module tier, attaching methods/fields/consts to
4
+ their owning namespace, resolving the superclass (EXTENDS) and mixins (INCLUDES) to project
5
+ namespaces, the `require` graph (IMPORTS) to project files, and best-effort call resolution.
6
+
7
+ Name-based only -- this is the fast tree-sitter engine, so every resolved CALLS/EXTENDS/INCLUDES
8
+ edge is stamped `resolution="name"`. Ruby is DYNAMIC (open classes, method_missing, no static
9
+ receiver types), so this pass is deliberately conservative:
10
+
11
+ - Receiverless (`foo`) and `self.foo` calls resolve against the enclosing class/module's own
12
+ methods and its project ancestors (superclass chain + included modules), then top-level
13
+ functions. `Const.foo` / `A::B.foo` resolve to a class/singleton method on that project
14
+ namespace (`Foo.new` resolves to `Foo#initialize`). `super` resolves the same-named method up
15
+ the ancestor chain.
16
+ - A `Const.foo` whose constant is NOT a project namespace is a nameable external symbol
17
+ (`JSON.parse`, `Net::HTTP.get`) -> an ADR-0004 placeholder Function reached by an ordinary CALLS
18
+ edge, healed if the defining repo is later ingested.
19
+ - Calls on a *local/@ivar* receiver (`x.foo`, `@store.foo`) and complex chains (`a.b.foo`) are too
20
+ dynamic to name without type inference -> dropped (no wrong guess), left for a deep pass.
21
+
22
+ Unresolved intra-project references produce no edge rather than a wrong guess -- the same
23
+ trade-off as the Rust/Go/Java ingestors."""
24
+
25
+ from __future__ import annotations
26
+
27
+ from collections import defaultdict
28
+ from collections.abc import Iterator
29
+ from dataclasses import dataclass, field
30
+
31
+ from auryn.core.graph_model import GraphEdge, GraphNode
32
+ from auryn.ingestors.ruby import ids
33
+ from auryn.ingestors.ruby.raw_model import RawFile, RawMethod, RawModule
34
+
35
+ # ADR 0004: constant-receiver calls into these well-known Ruby core/stdlib namespaces surface with
36
+ # origin="stdlib" (a terminal external that never resolves to an ingested repo); any other external
37
+ # constant is origin="external" (a candidate a sibling repo could later define). Not exhaustive --
38
+ # covers the common surface. Matched on the FIRST `::` segment (`Net::HTTP` -> `Net`).
39
+ _STDLIB_ROOTS = frozenset({
40
+ "Kernel", "Object", "BasicObject", "Module", "Class", "Comparable", "Enumerable",
41
+ "String", "Symbol", "Integer", "Float", "Numeric", "Array", "Hash", "Set", "Range",
42
+ "Struct", "Time", "Date", "DateTime", "File", "Dir", "IO", "Math", "Random",
43
+ "Regexp", "MatchData", "Proc", "Method", "Thread", "Mutex", "Fiber", "Marshal",
44
+ "JSON", "YAML", "Base64", "Digest", "SecureRandom", "OpenSSL", "Net", "URI", "Socket",
45
+ "Logger", "ObjectSpace", "GC", "Process", "Signal", "ENV", "ARGV", "StringIO", "Tempfile",
46
+ })
47
+
48
+
49
+ @dataclass
50
+ class _NS:
51
+ """A merged namespace accumulator (reopened class/module -> one entry keyed by ns_id)."""
52
+ ns_id: str
53
+ label: str # "Class" | "Module"
54
+ qualified: str
55
+ simple: str
56
+ file_id: str
57
+ first: RawModule
58
+ parent_qualified: str
59
+ superclasses: list[str] = field(default_factory=list)
60
+ includes: list = field(default_factory=list) # RawInclude
61
+ methods: list = field(default_factory=list) # (RawMethod,)
62
+ fields: list = field(default_factory=list) # RawField
63
+ consts: list = field(default_factory=list) # RawConst
64
+
65
+
66
+ @dataclass
67
+ class _Callable:
68
+ id: str
69
+ label: str # "Function" | "Method"
70
+ scope_id: str # owning ns_id (Method) or project_id (Function)
71
+ owner: _NS | None
72
+ raw: RawMethod
73
+
74
+
75
+ def resolve(raw_files, project_id: str) -> Iterator[GraphNode | GraphEdge]:
76
+ # -- files -----------------------------------------------------------------------------
77
+ file_ids: dict[str, str] = {}
78
+ norm_index: dict[str, str] = {} # normalized rel path -> file_id (for require resolution)
79
+ for rf in raw_files:
80
+ fid = ids.file_id(project_id, rf.path)
81
+ file_ids[rf.path] = fid
82
+ norm_index[_norm(rf.path)] = fid
83
+ yield GraphNode("File", {"id": fid}, {"name": _basename(rf.path), "path": _norm(rf.path)})
84
+ yield GraphEdge("HAS_FILE", "Project", {"id": project_id}, "File", {"id": fid})
85
+
86
+ # -- collect + merge namespaces --------------------------------------------------------
87
+ registry: dict[str, _NS] = {}
88
+ order: list[str] = [] # ns_ids in first-seen order (deterministic emission)
89
+ for rf in raw_files:
90
+ _collect(rf, project_id, "", file_ids[rf.path], registry, order)
91
+
92
+ by_qualified: dict[str, _NS] = {}
93
+ by_simple: dict[str, list[_NS]] = defaultdict(list)
94
+ for ns_id in order:
95
+ ns = registry[ns_id]
96
+ by_qualified.setdefault(ns.qualified, ns)
97
+ by_simple[ns.simple].append(ns)
98
+
99
+ # -- callables + member indexes --------------------------------------------------------
100
+ callables: list[_Callable] = []
101
+ function_index: dict[str, list[str]] = defaultdict(list) # name -> [func_id]
102
+ # ns_id -> name -> [(method_id, is_singleton)]
103
+ method_map: dict[str, dict[str, list[tuple[str, bool]]]] = defaultdict(lambda: defaultdict(list))
104
+
105
+ for rf in raw_files: # top-level defs -> Functions on the Project
106
+ for m in rf.methods:
107
+ if m.kind != "FUNCTION":
108
+ continue
109
+ fid = ids.function_id(project_id, m.name, [p.name for p in m.parameters])
110
+ callables.append(_Callable(fid, "Function", project_id, None, m))
111
+ function_index[m.name].append(fid)
112
+
113
+ for ns_id in order:
114
+ ns = registry[ns_id]
115
+ for m in ns.methods:
116
+ mid = ids.method_id(ns_id, m.name, [p.name for p in m.parameters], m.is_singleton)
117
+ callables.append(_Callable(mid, "Method", ns_id, ns, m))
118
+ method_map[ns_id][m.name].append((mid, m.is_singleton))
119
+
120
+ ancestors = _build_ancestors(order, registry, by_qualified, by_simple)
121
+
122
+ # -- pass 1: nodes + structural edges (landing nodes for pass 2) -----------------------
123
+ for ns_id in order:
124
+ yield from _emit_namespace(registry[ns_id], project_id, by_qualified)
125
+ for cal in callables:
126
+ yield from _emit_callable(cal, project_id)
127
+
128
+ # -- pass 2: EXTENDS, INCLUDES, IMPORTS, CALLS -----------------------------------------
129
+ for ns_id in order:
130
+ ns = registry[ns_id]
131
+ if ns.label == "Class":
132
+ for sc in ns.superclasses:
133
+ target = _resolve_ns(sc, by_qualified, by_simple)
134
+ if target is not None and target.label == "Class" and target.ns_id != ns.ns_id:
135
+ yield GraphEdge("EXTENDS", "Class", {"id": ns.ns_id}, "Class", {"id": target.ns_id},
136
+ {"resolution": "name"})
137
+ break # a Ruby class has a single superclass
138
+ emitted_inc: set[str] = set()
139
+ for inc in ns.includes:
140
+ target = _resolve_ns(inc.name, by_qualified, by_simple)
141
+ if target is None or target.label != "Module" or target.ns_id in emitted_inc:
142
+ continue
143
+ emitted_inc.add(target.ns_id)
144
+ yield GraphEdge("INCLUDES", ns.label, {"id": ns.ns_id}, "Module", {"id": target.ns_id},
145
+ {"kind": inc.kind, "resolution": "name"})
146
+
147
+ for rf in raw_files:
148
+ yield from _emit_imports(rf, file_ids[rf.path], norm_index)
149
+
150
+ emitted_externs: set[str] = set()
151
+ for cal in callables:
152
+ yield from _emit_calls(cal, method_map, ancestors, function_index, by_qualified, by_simple,
153
+ emitted_externs)
154
+
155
+
156
+ # -- collection ----------------------------------------------------------------------------
157
+
158
+ def _collect(scope, project_id: str, parent_qualified: str, file_id: str,
159
+ registry: dict[str, _NS], order: list[str]) -> None:
160
+ """Walk a RawFile / RawModule, merging each class/module into `registry` by its fully-qualified
161
+ id. `parent_qualified` is the lexical enclosing namespace's qualified name ("" at file top)."""
162
+ for rm in getattr(scope, "classes", []):
163
+ _merge_ns(rm, "Class", project_id, parent_qualified, file_id, registry, order)
164
+ for rm in getattr(scope, "modules", []):
165
+ _merge_ns(rm, "Module", project_id, parent_qualified, file_id, registry, order)
166
+
167
+
168
+ def _merge_ns(rm: RawModule, label: str, project_id: str, parent_qualified: str, file_id: str,
169
+ registry: dict[str, _NS], order: list[str]) -> None:
170
+ qualified = f"{parent_qualified}::{rm.name}" if parent_qualified else rm.name
171
+ ns_id = ids.class_id(project_id, qualified) if label == "Class" else ids.module_id(project_id, qualified)
172
+ ns = registry.get(ns_id)
173
+ if ns is None:
174
+ ns = _NS(
175
+ ns_id=ns_id, label=label, qualified=qualified, simple=qualified.split("::")[-1],
176
+ file_id=file_id, first=rm, parent_qualified=parent_qualified,
177
+ )
178
+ registry[ns_id] = ns
179
+ order.append(ns_id)
180
+ if rm.superclass:
181
+ ns.superclasses.append(rm.superclass)
182
+ ns.includes.extend(rm.includes)
183
+ ns.methods.extend(rm.methods)
184
+ ns.fields.extend(rm.fields)
185
+ ns.consts.extend(rm.consts)
186
+ _collect(rm, project_id, qualified, file_id, registry, order)
187
+
188
+
189
+ def _build_ancestors(order, registry, by_qualified, by_simple) -> dict[str, list[str]]:
190
+ """Per namespace: the project ancestor ns_ids (superclass chain first, then included modules),
191
+ for method-dispatch resolution. Cycle-safe and bounded."""
192
+ out: dict[str, list[str]] = {}
193
+ for ns_id in order:
194
+ ns = registry[ns_id]
195
+ chain: list[str] = []
196
+ seen = {ns_id}
197
+ # superclass chain
198
+ cur = ns
199
+ while cur is not None:
200
+ nxt = None
201
+ for sc in cur.superclasses:
202
+ cand = _resolve_ns(sc, by_qualified, by_simple)
203
+ if cand is not None and cand.label == "Class" and cand.ns_id not in seen:
204
+ nxt = cand
205
+ break
206
+ if nxt is None:
207
+ break
208
+ chain.append(nxt.ns_id)
209
+ seen.add(nxt.ns_id)
210
+ cur = nxt
211
+ # included modules of this ns and of every class in the chain
212
+ for base_id in [ns_id, *chain]:
213
+ for inc in registry[base_id].includes:
214
+ cand = _resolve_ns(inc.name, by_qualified, by_simple)
215
+ if cand is not None and cand.label == "Module" and cand.ns_id not in seen:
216
+ chain.append(cand.ns_id)
217
+ seen.add(cand.ns_id)
218
+ out[ns_id] = chain
219
+ return out
220
+
221
+
222
+ # -- pass 1 emitters -----------------------------------------------------------------------
223
+
224
+ def _emit_namespace(ns: _NS, project_id: str, by_qualified) -> Iterator[GraphNode | GraphEdge]:
225
+ rm = ns.first
226
+ props = {
227
+ "name": ns.simple,
228
+ "qualified_name": ns.qualified,
229
+ "source": rm.source,
230
+ "doc": rm.doc,
231
+ "line_start": rm.line_start,
232
+ "line_end": rm.line_end,
233
+ }
234
+ if ns.label == "Class":
235
+ props["superclass"] = ns.superclasses[0] if ns.superclasses else None
236
+ yield GraphNode(ns.label, {"id": ns.ns_id}, props)
237
+
238
+ parent = by_qualified.get(ns.parent_qualified) if ns.parent_qualified else None
239
+ if parent is not None:
240
+ rel = "HAS_CLASS" if ns.label == "Class" else "HAS_MODULE"
241
+ yield GraphEdge(rel, parent.label, {"id": parent.ns_id}, ns.label, {"id": ns.ns_id})
242
+ else:
243
+ rel = "HAS_CLASS" if ns.label == "Class" else "HAS_MODULE"
244
+ yield GraphEdge(rel, "Project", {"id": project_id}, ns.label, {"id": ns.ns_id})
245
+ yield GraphEdge("DEFINED_IN", ns.label, {"id": ns.ns_id}, "File", {"id": ns.file_id})
246
+
247
+ emitted_fields: set[str] = set()
248
+ for f in ns.fields:
249
+ fid = ids.field_id(ns.ns_id, f.name)
250
+ if fid in emitted_fields:
251
+ continue
252
+ emitted_fields.add(fid)
253
+ yield GraphNode("Field", {"id": fid}, {
254
+ "name": f.name, "access": f.access, "line_start": f.line_start, "line_end": f.line_end,
255
+ })
256
+ yield GraphEdge("HAS_FIELD", ns.label, {"id": ns.ns_id}, "Field", {"id": fid})
257
+
258
+ emitted_consts: set[str] = set()
259
+ for c in ns.consts:
260
+ cid = ids.const_id(ns.ns_id, c.name)
261
+ if cid in emitted_consts:
262
+ continue
263
+ emitted_consts.add(cid)
264
+ yield GraphNode("Const", {"id": cid}, {
265
+ "name": c.name, "value": c.value, "line_start": c.line_start, "line_end": c.line_end,
266
+ })
267
+ yield GraphEdge("HAS_CONST", ns.label, {"id": ns.ns_id}, "Const", {"id": cid})
268
+
269
+
270
+ def _emit_callable(cal: _Callable, project_id: str) -> Iterator[GraphNode | GraphEdge]:
271
+ m = cal.raw
272
+ props: dict = {
273
+ "name": m.name,
274
+ "kind": m.kind,
275
+ "visibility": m.visibility,
276
+ "signature": m.signature,
277
+ "source": m.source,
278
+ "doc": m.doc,
279
+ "line_start": m.line_start,
280
+ "line_end": m.line_end,
281
+ }
282
+ linkage = _linkage(cal)
283
+ if linkage is not None:
284
+ props["linkage_key"] = linkage
285
+ if cal.label == "Method":
286
+ props["is_singleton"] = m.is_singleton
287
+ yield GraphNode("Method", {"id": cal.id}, props)
288
+ yield GraphEdge("HAS_METHOD", cal.owner.label, {"id": cal.owner.ns_id}, "Method", {"id": cal.id})
289
+ else:
290
+ yield GraphNode("Function", {"id": cal.id}, props)
291
+ yield GraphEdge("HAS_FUNCTION", "Project", {"id": project_id}, "Function", {"id": cal.id})
292
+ for i, p in enumerate(m.parameters):
293
+ pid = ids.parameter_id(cal.id, i, p.name)
294
+ yield GraphNode("Parameter", {"id": pid}, {
295
+ "name": p.name, "kind": p.kind, "position": p.position, "default": p.default,
296
+ })
297
+ yield GraphEdge("HAS_PARAMETER", cal.label, {"id": cal.id}, "Parameter", {"id": pid})
298
+
299
+
300
+ def _linkage(cal: _Callable) -> str | None:
301
+ """ADR 0004 cross-repo key for a public callable (Ruby defaults to public), else None. In the
302
+ form a consumer writes: `Class#method` (instance), `Class.method` (class/singleton), or a bare
303
+ `name` (top-level function)."""
304
+ m = cal.raw
305
+ if m.visibility != "public":
306
+ return None
307
+ if cal.label == "Method":
308
+ sep = "." if m.is_singleton else "#"
309
+ return ids.extern_symbol_key(f"{cal.owner.qualified}{sep}{m.name}")
310
+ return ids.extern_symbol_key(m.name)
311
+
312
+
313
+ # -- pass 2: imports + calls ---------------------------------------------------------------
314
+
315
+ def _emit_imports(rf: RawFile, from_file_id: str, norm_index: dict[str, str]) -> Iterator[GraphEdge]:
316
+ emitted: set[str] = set()
317
+ for req in rf.requires:
318
+ target_id = _resolve_require(req, rf.path, norm_index)
319
+ if target_id is None or target_id == from_file_id or target_id in emitted:
320
+ continue
321
+ emitted.add(target_id)
322
+ resolution = "path" if req.kind == "require_relative" else "name"
323
+ yield GraphEdge("IMPORTS", "File", {"id": from_file_id}, "File", {"id": target_id},
324
+ {"resolution": resolution, "kind": req.kind, "target": req.target})
325
+
326
+
327
+ def _resolve_require(req, from_path: str, norm_index: dict[str, str]) -> str | None:
328
+ target = req.target
329
+ if not target:
330
+ return None
331
+ candidate = target if target.endswith(".rb") else target + ".rb"
332
+ if req.kind == "require_relative":
333
+ base = _norm(from_path).rsplit("/", 1)[0] if "/" in _norm(from_path) else ""
334
+ joined = _norm(f"{base}/{candidate}" if base else candidate)
335
+ joined = _collapse(joined)
336
+ return norm_index.get(joined)
337
+ # `require "x/y"`: $LOAD_PATH-relative -> match a project file by exact or suffix path.
338
+ cand = _norm(candidate)
339
+ if cand in norm_index:
340
+ return norm_index[cand]
341
+ suffix = "/" + cand
342
+ matches = sorted(fid_path for fid_path in norm_index if fid_path.endswith(suffix))
343
+ return norm_index[matches[0]] if matches else None
344
+
345
+
346
+ def _emit_calls(cal: _Callable, method_map, ancestors, function_index, by_qualified, by_simple,
347
+ emitted_externs: set[str]) -> Iterator[GraphNode | GraphEdge]:
348
+ emitted: set[str] = set()
349
+ for call in cal.raw.calls:
350
+ hit = _resolve_call(call, cal, method_map, ancestors, function_index, by_qualified, by_simple)
351
+ if hit is None:
352
+ continue
353
+ if isinstance(hit, _External):
354
+ if hit.eid in emitted:
355
+ continue
356
+ emitted.add(hit.eid)
357
+ if hit.eid not in emitted_externs:
358
+ emitted_externs.add(hit.eid)
359
+ yield GraphNode("Function", {"id": hit.eid}, {
360
+ "name": hit.name, "qualified_name": hit.qualified, "resolved": False,
361
+ "origin": hit.origin, "linkage_key": hit.eid,
362
+ })
363
+ yield GraphEdge("CALLS", cal.label, {"id": cal.id}, "Function", {"id": hit.eid},
364
+ {"resolution": "external", "receiver": hit.qualifier})
365
+ continue
366
+ target_id, extra = hit
367
+ if target_id == cal.id or target_id in emitted:
368
+ continue
369
+ emitted.add(target_id)
370
+ target_label = "Function" if ".func." in target_id else "Method"
371
+ yield GraphEdge("CALLS", cal.label, {"id": cal.id}, target_label, {"id": target_id},
372
+ {"resolution": "name", **extra})
373
+
374
+
375
+ @dataclass
376
+ class _External:
377
+ eid: str
378
+ name: str
379
+ qualified: str
380
+ origin: str
381
+ qualifier: str
382
+
383
+
384
+ def _resolve_call(call, cal: _Callable, method_map, ancestors, function_index, by_qualified, by_simple):
385
+ """A resolved local `(target_id, extra_props)`, an `_External` placeholder for a nameable
386
+ out-of-project constant-receiver call (ADR 0004), or None to drop."""
387
+ owner_id = cal.owner.ns_id if cal.owner is not None else None
388
+
389
+ if call.kind in ("command", "self"):
390
+ if owner_id is not None:
391
+ mid = _instance_method(owner_id, call.name, method_map, ancestors)
392
+ if mid:
393
+ return mid, {}
394
+ if call.kind == "command": # a top-level function is only reachable receiverless
395
+ fns = function_index.get(call.name)
396
+ if fns:
397
+ return sorted(fns)[0], {}
398
+ return None
399
+
400
+ if call.kind == "super":
401
+ if owner_id is None:
402
+ return None
403
+ for aid in ancestors.get(owner_id, []):
404
+ for (mid, is_singleton) in method_map.get(aid, {}).get(cal.raw.name, []):
405
+ if not is_singleton:
406
+ return mid, {}
407
+ return None
408
+
409
+ if call.kind == "constant":
410
+ ns = _resolve_ns(call.qualifier, by_qualified, by_simple)
411
+ if ns is not None:
412
+ if call.name == "new" and ns.label == "Class": # Foo.new -> Foo#initialize
413
+ mid = _instance_method(ns.ns_id, "initialize", method_map, ancestors)
414
+ if mid:
415
+ return mid, {"receiver": ns.qualified}
416
+ mid = _class_method(ns.ns_id, call.name, method_map, ancestors)
417
+ if mid:
418
+ return mid, {"receiver": ns.qualified}
419
+ return None # project namespace but no such class method -> intra-project dangling
420
+ # a constant that names no project namespace -> external (stdlib/gem)
421
+ qualified = f"{call.qualifier}.{call.name}"
422
+ root = call.qualifier.split("::", 1)[0]
423
+ origin = "stdlib" if root in _STDLIB_ROOTS else "external"
424
+ return _External(ids.extern_symbol_key(qualified), call.name, qualified, origin, call.qualifier)
425
+
426
+ # "instance" (local/@ivar receiver) and "chain" -> too dynamic to name -> drop.
427
+ return None
428
+
429
+
430
+ def _instance_method(owner_id, name, method_map, ancestors) -> str | None:
431
+ for aid in [owner_id, *ancestors.get(owner_id, [])]:
432
+ for (mid, is_singleton) in method_map.get(aid, {}).get(name, []):
433
+ if not is_singleton:
434
+ return mid
435
+ return None
436
+
437
+
438
+ def _class_method(owner_id, name, method_map, ancestors) -> str | None:
439
+ for aid in [owner_id, *ancestors.get(owner_id, [])]:
440
+ for (mid, is_singleton) in method_map.get(aid, {}).get(name, []):
441
+ if is_singleton:
442
+ return mid
443
+ return None
444
+
445
+
446
+ # -- helpers -------------------------------------------------------------------------------
447
+
448
+ def _resolve_ns(name: str | None, by_qualified, by_simple) -> _NS | None:
449
+ """Resolve a written constant name to a project namespace: try the fully-qualified path first,
450
+ then the bare simple name (last segment), deterministically on ambiguity."""
451
+ if not name:
452
+ return None
453
+ key = name.replace("::", "::").strip()
454
+ if key in by_qualified:
455
+ return by_qualified[key]
456
+ # strip a leading `::` absolute qualifier, retry
457
+ if key.startswith("::") and key[2:] in by_qualified:
458
+ return by_qualified[key[2:]]
459
+ simple = key.split("::")[-1]
460
+ matches = by_simple.get(simple)
461
+ if matches:
462
+ return sorted(matches, key=lambda n: n.ns_id)[0]
463
+ return None
464
+
465
+
466
+ def _norm(path: str) -> str:
467
+ return path.replace("\\", "/").lstrip("./")
468
+
469
+
470
+ def _collapse(path: str) -> str:
471
+ """Collapse `.`/`..` segments in a normalized relative path (for require_relative)."""
472
+ parts: list[str] = []
473
+ for seg in path.split("/"):
474
+ if seg in ("", "."):
475
+ continue
476
+ if seg == "..":
477
+ if parts:
478
+ parts.pop()
479
+ else:
480
+ parts.append(seg)
481
+ return "/".join(parts)
482
+
483
+
484
+ def _basename(path: str) -> str:
485
+ return _norm(path).rsplit("/", 1)[-1]
@@ -0,0 +1,61 @@
1
+ """Graph schema (node/edge labels) the Ruby ingestor writes. git_sync passes NODE_SCHEMAS to
2
+ setup_schema()/read_fingerprints() so the delta-sync pipeline (core/graph_sync.py) can index
3
+ and diff this project's Ruby subgraph.
4
+
5
+ Ruby is class-based (like Python/Java/C#), so the model uses a `Class` tier -- not Rust's
6
+ Struct/Trait -- alongside a `Module` tier (Ruby modules are namespaces AND mixins). Callables
7
+ split into free `Function`s (a top-level `def`, owned by a Module/Project via HAS_FUNCTION) and
8
+ `Method`s (a `def` inside a class/module, bound via HAS_METHOD; `is_singleton` marks a
9
+ class/singleton method). Attributes declared by `attr_accessor`/`attr_reader`/`attr_writer` are
10
+ `Field`s; uppercase-initial constant assignments are `Const`s.
11
+
12
+ Ruby semantic edges: EXTENDS carries the superclass (`class Dog < Animal` -> Dog EXTENDS Animal);
13
+ INCLUDES carries a mixin (`include`/`prepend`/`extend M` -> Class|Module INCLUDES Module, with a
14
+ `kind` property) -- the Ruby analog of Rust's IMPLEMENTS / Go's EMBEDS. IMPORTS carries the
15
+ `require`/`require_relative` graph (File -> File) once a require resolves to a project file.
16
+
17
+ Every cross-entity semantic edge carries a `resolution` provenance ("name" = the fast tree-sitter
18
+ engine's name-based match; "external" = a nameable out-of-project placeholder, ADR 0004). A deep
19
+ Ruby resolver would re-emit the same ids with a stronger provenance -- the two-phase model,
20
+ matching the discipline of the Rust/Go/Python ingestors.
21
+
22
+ The shared cross-ingestor contract is honoured: callables are `Function`/`Method`, the call edge
23
+ is `CALLS` (carrying `resolution`), and `Parameter`/`HAS_PARAMETER`/`EXTENDS`/`DEFINED_IN` match
24
+ the other ingestors."""
25
+
26
+ from __future__ import annotations
27
+
28
+ from auryn.core.graph_model import EdgeSchema, NodeSchema
29
+
30
+ NODE_SCHEMAS = [
31
+ NodeSchema(label="Project", indexed_properties=("name",)),
32
+ NodeSchema(label="Module", indexed_properties=("name",)),
33
+ NodeSchema(label="File", indexed_properties=("path",)),
34
+ NodeSchema(label="Class", indexed_properties=("name",)),
35
+ NodeSchema(label="Function", indexed_properties=("name", "linkage_key")), # linkage_key: ADR 0004 cross-repo
36
+ NodeSchema(label="Method", indexed_properties=("name", "linkage_key")), # linkage_key: ADR 0004 cross-repo
37
+ NodeSchema(label="Field", indexed_properties=("name",)),
38
+ NodeSchema(label="Parameter", indexed_properties=("name",)),
39
+ NodeSchema(label="Const", indexed_properties=("name",)),
40
+ ]
41
+
42
+ EDGE_SCHEMAS = [
43
+ # Containment backbone -- pure structure, no properties (as in Rust/Java/Python).
44
+ EdgeSchema(rel_type="HAS_MODULE"), # Project|Module|Class -> Module
45
+ EdgeSchema(rel_type="HAS_CLASS"), # Project|Module|Class -> Class (incl. nested classes)
46
+ EdgeSchema(rel_type="HAS_FILE"), # Project -> File
47
+ EdgeSchema(rel_type="HAS_FUNCTION"), # Project|Module -> Function (top-level defs)
48
+ EdgeSchema(rel_type="HAS_METHOD"), # Class|Module -> Method
49
+ EdgeSchema(rel_type="HAS_FIELD"), # Class|Module -> Field (attr_accessor/reader/writer)
50
+ EdgeSchema(rel_type="HAS_PARAMETER"), # Function|Method -> Parameter
51
+ EdgeSchema(rel_type="HAS_CONST"), # Project|Module|Class -> Const
52
+ EdgeSchema(rel_type="DEFINED_IN"), # Class|Module -> File
53
+ # Semantic layer.
54
+ EdgeSchema(rel_type="EXTENDS"), # Class -> Class (superclass); {resolution}
55
+ EdgeSchema(rel_type="INCLUDES"), # Class|Module -> Module (mixin); {kind, resolution}
56
+ EdgeSchema(rel_type="CALLS"), # Function|Method -> Function|Method; {resolution, receiver?}
57
+ EdgeSchema(rel_type="IMPORTS"), # File -> File (require/require_relative); {resolution, kind, target}
58
+ ]
59
+
60
+ # Every label that can be an EXTENDS/INCLUDES/HAS_CLASS/HAS_MODULE namespace endpoint.
61
+ TYPE_LABELS = ("Class", "Module")