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.
File without changes
@@ -0,0 +1,320 @@
1
+ """parse_file(path) -> RawFile: the parallelizable phase-1 unit (pure function, no shared
2
+ state -- safe under a ProcessPoolExecutor; only picklable raw_model dataclasses are returned,
3
+ no tree-sitter node crosses the boundary). parse_source(source, path_label) holds the logic
4
+ and takes raw bytes, so a git blob can be parsed without touching disk.
5
+
6
+ Every node type / field name below was confirmed empirically against tree-sitter-java 0.23.5
7
+ (see the package's grammar probe), not assumed:
8
+
9
+ - top level: `package_declaration` (child scoped_identifier/identifier), `import_declaration`
10
+ (scoped_identifier + optional `asterisk`/`static`), and the type declarations
11
+ `class_declaration` / `interface_declaration` / `enum_declaration` / `record_declaration`.
12
+ - class: fields `name`, `type_parameters`, `superclass` (single), `interfaces`
13
+ (super_interfaces -> type_list), `body` (class_body); interface uses `extends_interfaces`.
14
+ - members: `field_declaration` (modifiers + [type] + repeated [declarator] variable_declarator),
15
+ `method_declaration` ([type]=return, [name], [parameters], optional `throws`, [body]),
16
+ `constructor_declaration` (no return type), nested type declarations.
17
+ - modifiers: keyword tokens (public/static/final/abstract/...) are ANONYMOUS children of the
18
+ `modifiers` node; annotations are its named `marker_annotation`/`annotation` children.
19
+ - calls: `method_invocation` ([object]?, [name], [arguments]) and `object_creation_expression`
20
+ ([type], [arguments]); `super(...)`/`this(...)` are explicit_constructor_invocation, ignored.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ from pathlib import Path
26
+
27
+ from auryn.core.docstrings import leading_comment
28
+ from auryn.ingestors.java.grammar import new_parser
29
+ from auryn.ingestors.java.raw_model import (
30
+ RawAnnotation,
31
+ RawCall,
32
+ RawEnumMember,
33
+ RawField,
34
+ RawFile,
35
+ RawImport,
36
+ RawMethod,
37
+ RawParameter,
38
+ RawType,
39
+ )
40
+
41
+ _TYPE_DECL_KINDS = {
42
+ "class_declaration": "Class",
43
+ "interface_declaration": "Interface",
44
+ "enum_declaration": "Enum",
45
+ "record_declaration": "Record",
46
+ }
47
+ _ACCESS_KEYWORDS = ("public", "private", "protected")
48
+
49
+
50
+ def parse_file(path: str) -> RawFile:
51
+ return parse_source(Path(path).read_bytes(), path)
52
+
53
+
54
+ def parse_source(source: bytes, path_label: str) -> RawFile:
55
+ tree = new_parser().parse(source)
56
+ rf = RawFile(path=path_label)
57
+
58
+ def txt(node) -> str:
59
+ return source[node.start_byte : node.end_byte].decode("utf-8", "replace") if node else ""
60
+
61
+ def lines(node) -> tuple[int, int]:
62
+ return node.start_point[0] + 1, node.end_point[0] + 1
63
+
64
+ def field(node, name):
65
+ return node.child_by_field_name(name) if node is not None else None
66
+
67
+ def first_type_name(node) -> str | None:
68
+ """The bare simple name a type node denotes: `Base` for `Base`, `Base<T>`
69
+ (generic_type), or `pkg.Base` (scoped_type_identifier). None if it names nothing."""
70
+ if node is None:
71
+ return None
72
+ if node.type == "type_identifier":
73
+ return txt(node)
74
+ if node.type == "generic_type":
75
+ return first_type_name(node.child(0))
76
+ if node.type == "scoped_type_identifier":
77
+ # last segment is the simple name
78
+ last = None
79
+ for c in node.children:
80
+ if c.type == "type_identifier":
81
+ last = c
82
+ return txt(last) if last is not None else None
83
+ # descend to the first type_identifier we can find
84
+ stack = list(node.children)
85
+ while stack:
86
+ n = stack.pop(0)
87
+ if n.type == "type_identifier":
88
+ return txt(n)
89
+ stack.extend(n.children)
90
+ return None
91
+
92
+ def modifiers_of(node) -> tuple[list[str], list[RawAnnotation]]:
93
+ """(keyword modifiers, annotations) from a declaration's `modifiers` child."""
94
+ mods_node = next((c for c in node.children if c.type == "modifiers"), None)
95
+ if mods_node is None:
96
+ return [], []
97
+ keywords: list[str] = []
98
+ annotations: list[RawAnnotation] = []
99
+ for c in mods_node.children:
100
+ if c.type in ("marker_annotation", "annotation"):
101
+ annotations.append(_annotation(c))
102
+ elif not c.is_named: # public/private/protected/static/final/abstract/...
103
+ keywords.append(c.type)
104
+ return keywords, annotations
105
+
106
+ def _annotation(node) -> RawAnnotation:
107
+ name = first_type_name(field(node, "name")) or txt(field(node, "name"))
108
+ args: list[str] = []
109
+ arglist = field(node, "arguments")
110
+ if arglist is not None:
111
+ for a in arglist.named_children:
112
+ args.append(txt(a))
113
+ return RawAnnotation(name=name or "", arguments=args)
114
+
115
+ def accessibility(keywords: list[str]) -> str:
116
+ for kw in _ACCESS_KEYWORDS:
117
+ if kw in keywords:
118
+ return kw
119
+ return "package" # Java's default (package-private)
120
+
121
+ def type_parameters(node) -> list[str]:
122
+ tp = field(node, "type_parameters")
123
+ if tp is None:
124
+ return []
125
+ out = []
126
+ for c in tp.named_children:
127
+ if c.type == "type_parameter":
128
+ ident = next((g for g in c.children if g.type == "type_identifier"), None)
129
+ if ident is not None:
130
+ out.append(txt(ident))
131
+ return out
132
+
133
+ def interface_names(super_interfaces_or_extends) -> list[str]:
134
+ if super_interfaces_or_extends is None:
135
+ return []
136
+ type_list = next((c for c in super_interfaces_or_extends.children if c.type == "type_list"), None)
137
+ if type_list is None:
138
+ return []
139
+ out = []
140
+ for c in type_list.named_children:
141
+ nm = first_type_name(c)
142
+ if nm:
143
+ out.append(nm)
144
+ return out
145
+
146
+ def parameters(formal_parameters_node) -> list[RawParameter]:
147
+ if formal_parameters_node is None:
148
+ return []
149
+ out: list[RawParameter] = []
150
+ pos = 0
151
+ for c in formal_parameters_node.children:
152
+ if c.type == "formal_parameter":
153
+ name_node = field(c, "name")
154
+ out.append(
155
+ RawParameter(
156
+ name=txt(name_node), type=_type_text(field(c, "type")), position=pos,
157
+ is_final=any(g.type == "final" for g in c.children),
158
+ )
159
+ )
160
+ pos += 1
161
+ elif c.type == "spread_parameter": # `T... name`
162
+ type_node = next((g for g in c.children if g.type not in ("...", "variable_declarator")), None)
163
+ declarator = next((g for g in c.children if g.type == "variable_declarator"), None)
164
+ name_node = field(declarator, "name") if declarator is not None else None
165
+ out.append(
166
+ RawParameter(
167
+ name=txt(name_node), type=_type_text(type_node), position=pos, is_varargs=True,
168
+ )
169
+ )
170
+ pos += 1
171
+ return out
172
+
173
+ def _type_text(node) -> str:
174
+ return " ".join(txt(node).split()) if node is not None else ""
175
+
176
+ def collect_calls(body) -> list[RawCall]:
177
+ if body is None:
178
+ return []
179
+ out: list[RawCall] = []
180
+ seen: set = set()
181
+ stack = [body]
182
+ while stack:
183
+ n = stack.pop()
184
+ if n.type == "method_invocation":
185
+ name_node = field(n, "name")
186
+ obj = field(n, "object")
187
+ recv = None
188
+ if obj is not None and obj.type == "this":
189
+ recv = "this"
190
+ elif obj is not None and obj.type == "identifier":
191
+ recv = txt(obj)
192
+ nm = txt(name_node)
193
+ key = (nm, recv, False)
194
+ if nm and key not in seen:
195
+ seen.add(key)
196
+ out.append(RawCall(name=nm, receiver=recv, is_new=False))
197
+ elif n.type == "object_creation_expression":
198
+ nm = first_type_name(field(n, "type"))
199
+ key = (nm, None, True)
200
+ if nm and key not in seen:
201
+ seen.add(key)
202
+ out.append(RawCall(name=nm, receiver=None, is_new=True))
203
+ stack.extend(n.children)
204
+ return out
205
+
206
+ def build_method(node, kind: str) -> RawMethod:
207
+ keywords, annotations = modifiers_of(node)
208
+ throws_node = next((c for c in node.children if c.type == "throws"), None)
209
+ throws = [first_type_name(c) for c in throws_node.named_children] if throws_node is not None else []
210
+ body = field(node, "body")
211
+ ls, le = lines(node)
212
+ return RawMethod(
213
+ name=txt(field(node, "name")),
214
+ kind=kind,
215
+ accessibility=accessibility(keywords),
216
+ modifiers=keywords,
217
+ return_type=_type_text(field(node, "type")) if kind == "ORDINARY" else None,
218
+ parameters=parameters(field(node, "parameters")),
219
+ throws=[t for t in throws if t],
220
+ annotations=annotations,
221
+ calls=collect_calls(body),
222
+ source=txt(node),
223
+ doc=leading_comment(node, source),
224
+ line_start=ls, line_end=le,
225
+ )
226
+
227
+ def build_fields(node) -> list[RawField]:
228
+ keywords, annotations = modifiers_of(node)
229
+ type_text = _type_text(field(node, "type"))
230
+ ls, le = lines(node)
231
+ out = []
232
+ for declarator in node.children:
233
+ if declarator.type != "variable_declarator":
234
+ continue
235
+ name_node = field(declarator, "name")
236
+ out.append(
237
+ RawField(
238
+ name=txt(name_node), type=type_text, accessibility=accessibility(keywords),
239
+ modifiers=keywords, annotations=annotations, line_start=ls, line_end=le,
240
+ )
241
+ )
242
+ return out
243
+
244
+ def enum_members(enum_body) -> list[RawEnumMember]:
245
+ out = []
246
+ for c in enum_body.children:
247
+ if c.type == "enum_constant":
248
+ arglist = field(c, "arguments")
249
+ args = [txt(a) for a in arglist.named_children] if arglist is not None else []
250
+ out.append(RawEnumMember(name=txt(field(c, "name")), arguments=args))
251
+ return out
252
+
253
+ def dispatch_member(member, rt: RawType) -> None:
254
+ if member.type == "field_declaration":
255
+ rt.fields.extend(build_fields(member))
256
+ elif member.type == "method_declaration":
257
+ rt.methods.append(build_method(member, "ORDINARY"))
258
+ elif member.type == "constructor_declaration":
259
+ rt.methods.append(build_method(member, "CONSTRUCTOR"))
260
+ elif member.type == "compact_constructor_declaration": # record compact ctor
261
+ rt.methods.append(build_method(member, "CONSTRUCTOR"))
262
+ elif member.type in _TYPE_DECL_KINDS:
263
+ rt.nested_types.append(build_type(member, rt.package))
264
+
265
+ def build_type(node, package: str) -> RawType:
266
+ kind = _TYPE_DECL_KINDS[node.type]
267
+ keywords, annotations = modifiers_of(node)
268
+ ls, le = lines(node)
269
+ rt = RawType(
270
+ kind=kind, name=txt(field(node, "name")), package=package,
271
+ accessibility=accessibility(keywords), modifiers=keywords,
272
+ type_parameters=type_parameters(node), annotations=annotations,
273
+ source=txt(node), doc=leading_comment(node, source), line_start=ls, line_end=le,
274
+ )
275
+
276
+ if kind == "Class":
277
+ rt.superclass = first_type_name(field(node, "superclass"))
278
+ rt.interfaces = interface_names(field(node, "interfaces"))
279
+ elif kind == "Interface":
280
+ ext = next((c for c in node.children if c.type == "extends_interfaces"), None)
281
+ rt.interfaces = interface_names(ext)
282
+ elif kind in ("Enum", "Record"):
283
+ rt.interfaces = interface_names(field(node, "interfaces"))
284
+
285
+ if kind == "Record":
286
+ rt.record_components = parameters(field(node, "parameters"))
287
+
288
+ body = field(node, "body")
289
+ if body is None:
290
+ return rt
291
+
292
+ if body.type == "enum_body":
293
+ rt.enum_members = enum_members(body)
294
+ decls = next((c for c in body.children if c.type == "enum_body_declarations"), None)
295
+ if decls is not None:
296
+ for member in decls.children:
297
+ dispatch_member(member, rt)
298
+ return rt
299
+
300
+ for member in body.children: # class_body / interface_body
301
+ dispatch_member(member, rt)
302
+ return rt
303
+
304
+ for child in tree.root_node.children:
305
+ if child.type == "package_declaration":
306
+ name_node = next((c for c in child.children if c.type in ("scoped_identifier", "identifier")), None)
307
+ rf.package = txt(name_node)
308
+ elif child.type == "import_declaration":
309
+ name_node = next((c for c in child.children if c.type in ("scoped_identifier", "identifier")), None)
310
+ rf.imports.append(
311
+ RawImport(
312
+ name=txt(name_node),
313
+ is_static=any(c.type == "static" for c in child.children),
314
+ is_wildcard=any(c.type == "asterisk" for c in child.children),
315
+ )
316
+ )
317
+ elif child.type in _TYPE_DECL_KINDS:
318
+ rf.types.append(build_type(child, rf.package))
319
+
320
+ return rf
@@ -0,0 +1,177 @@
1
+ """Git-tracked (and directory) Java ingestion: moves a project's Java subgraph to a target
2
+ commit/tree by fully recomputing the target state and diffing it against the graph
3
+ (graph_sync.compute_delta) -- the same recompute-and-delta model as the C/C#/Python ingestors
4
+ (resolution is global -- the package-wide type/method index -- so a file-level diff can't tell
5
+ which untouched files a change affects).
6
+
7
+ Fast engine only for now: tree-sitter-java streams each `.java` blob (no disk materialization,
8
+ no build config) -> RawFile -> resolution.resolve(). A deep Eclipse JDT / javac pass (resolved
9
+ types, inherited-member calls, precise overload selection) would be added as the GitLanguage's
10
+ `deep_sync` (see plugin.py). Registered as the `java` GitLanguage for the multi-language
11
+ endpoint (core/ingest.py) in both ingest_repository (git) and ingest_directory (local)."""
12
+
13
+ from __future__ import annotations
14
+
15
+ import itertools
16
+ import logging
17
+ import time
18
+ from dataclasses import dataclass
19
+
20
+ from auryn.core.parallel import parse_blobs_ordered
21
+ from auryn.core.graph_model import GraphNode
22
+ from auryn.core.graph_sync import stream_apply
23
+ from auryn.core.registry import LanguageIngestResult
24
+ from auryn.ingestors.java import resolution
25
+ from auryn.ingestors.java.file_parser import parse_source
26
+ from auryn.ingestors.java.ids import project_id
27
+ from auryn.ingestors.java.plugin import EXCLUDED_DIR_NAMES as _EXCLUDED_DIR_NAMES
28
+ from auryn.ingestors.java.plugin import FILE_SUFFIXES as _FILE_SUFFIXES
29
+ from auryn.ingestors.java.schema import NODE_SCHEMAS
30
+
31
+ logger = logging.getLogger(__name__)
32
+
33
+
34
+ @dataclass
35
+ class SyncStats:
36
+ nodes_added: int = 0
37
+ nodes_updated: int = 0
38
+ nodes_removed: int = 0
39
+ edges_added: int = 0
40
+ edges_updated: int = 0
41
+ edges_removed: int = 0
42
+ commit_sha: str = ""
43
+ elapsed_seconds: float = 0.0
44
+ files_parsed: int = 0
45
+ files_cached: int = 0
46
+
47
+
48
+ def sync_at(writer, source, target_sha: str, project_name: str, repo_uri: str, ref: str | None) -> SyncStats:
49
+ """Recompute the whole Java subgraph at `target_sha` and delta it onto the graph. `source`
50
+ is duck-typed (GitRepoCache or LocalDirectorySource): only list_files/read_blob used."""
51
+ started = time.monotonic()
52
+ proj_id = project_id(project_name)
53
+
54
+ writer.setup_schema(NODE_SCHEMAS) # brings the graph key into existence before the first read
55
+ current_sha = writer.get_property("Project", {"id": proj_id}, "commit_sha")
56
+ if current_sha == target_sha:
57
+ return SyncStats(commit_sha=target_sha, elapsed_seconds=time.monotonic() - started)
58
+
59
+ # Incremental resync (ADR 0005, authored-shared engine): when a prior graph exists at a
60
+ # different, reachable commit, move it by processing only the git diff + its graph-derived blast
61
+ # radius instead of recomputing the whole tree -- see incremental.py. Any failure falls back to
62
+ # the full recompute below (which leaves the graph untouched until it writes).
63
+ if current_sha and current_sha != target_sha:
64
+ incr = _route(writer, source, target_sha, ref, current_sha,
65
+ project_name=project_name, repo_uri=repo_uri)
66
+ if incr is not None:
67
+ return _finish(writer, proj_id, source, incr)
68
+
69
+ entries = [
70
+ (path, blob_sha)
71
+ for suffix in _FILE_SUFFIXES
72
+ for path, blob_sha in source.list_files(target_sha, suffix, set(_EXCLUDED_DIR_NAMES))
73
+ ]
74
+ files = parse_blobs_ordered(
75
+ entries, source.read_blob, parse_source,
76
+ preload=["auryn.ingestors.java.file_parser"], logger=logger,
77
+ )
78
+
79
+ project_node = GraphNode(
80
+ "Project", {"id": proj_id}, {"name": project_name, "repo_uri": repo_uri, "commit_sha": target_sha, "ref": ref}
81
+ )
82
+
83
+ def make_target(): # re-iterable: stream_apply runs it once for nodes, once for edges
84
+ return itertools.chain([project_node], resolution.resolve(files, proj_id))
85
+
86
+ return _finish(writer, proj_id, source,
87
+ _apply(writer, proj_id, make_target, target_sha, started, files_parsed=len(files)))
88
+
89
+
90
+ def _route(writer, source, target_sha, ref, current_sha, *, project_name, repo_uri) -> "SyncStats | None":
91
+ """Attempt an incremental resync via the shared engine's git routing; return SyncStats or None to
92
+ fall back to the full recompute. JAVA_SPEC sets `provenance_rels`, so route_incremental dispatches
93
+ to the authored-shared engine (incremental_sync_authored)."""
94
+ from auryn.core.incremental_scoped import route_incremental
95
+ from auryn.ingestors.java.incremental import JAVA_SPEC
96
+
97
+ s = route_incremental(
98
+ writer, JAVA_SPEC, source, target_sha, ref, current_sha,
99
+ project_name=project_name, repo_uri=repo_uri, logger=logger,
100
+ )
101
+ if s is None:
102
+ return None
103
+ return SyncStats(
104
+ nodes_added=s.nodes_added, nodes_updated=s.nodes_updated, nodes_removed=s.nodes_removed,
105
+ edges_added=s.edges_added, edges_updated=s.edges_updated, edges_removed=s.edges_removed,
106
+ commit_sha=s.commit_sha, elapsed_seconds=s.elapsed_seconds,
107
+ files_parsed=s.files_parsed, files_cached=s.files_cached,
108
+ )
109
+
110
+
111
+ def _finish(writer, proj_id: str, source, result: SyncStats) -> SyncStats:
112
+ """Record the working-tree base for the next save-triggered incremental resync (no-op for
113
+ git/plain-dir sources)."""
114
+ from auryn.core.incremental_scoped import stamp_worktree
115
+ from auryn.core.local_source import WorkingTreeSource
116
+
117
+ if isinstance(source, WorkingTreeSource):
118
+ stamp_worktree(writer, proj_id, source, _FILE_SUFFIXES)
119
+ return result
120
+
121
+
122
+ def _apply(writer, proj_id: str, make_target, target_sha: str, started: float, files_parsed: int) -> SyncStats:
123
+ # Cross-repo reconciliation (ADR 0004): fold placeholder<->definer pairs among the linkages
124
+ # this ingest touched -- targeted index seeks, no scan. No-op unless the graph holds >1 repo.
125
+ from auryn.core.linkage import reconcile_linkages
126
+
127
+ # stream_apply writes the delta without materialising the target graph, and returns the
128
+ # linkage strings collected inline (see graph_sync.stream_apply / core.linkage).
129
+ labels = [s.label for s in NODE_SCHEMAS]
130
+ stats, reals, placeholders = stream_apply(writer, proj_id, labels, make_target)
131
+ reconcile_linkages(writer, reals, placeholders)
132
+
133
+ return SyncStats(
134
+ nodes_added=stats.nodes_added,
135
+ nodes_updated=stats.nodes_updated,
136
+ nodes_removed=stats.nodes_removed,
137
+ edges_added=stats.edges_added,
138
+ edges_updated=stats.edges_updated,
139
+ edges_removed=stats.edges_removed,
140
+ commit_sha=target_sha,
141
+ elapsed_seconds=time.monotonic() - started,
142
+ files_parsed=files_parsed,
143
+ files_cached=0,
144
+ )
145
+
146
+
147
+ def _git_language_sync(
148
+ writer,
149
+ source,
150
+ target_sha: str,
151
+ *,
152
+ repo_uri: str,
153
+ project_name: str,
154
+ solution_name: str | None,
155
+ ref: str | None,
156
+ cache_root=None,
157
+ ) -> LanguageIngestResult:
158
+ """GitLanguage adapter for the multi-language endpoint (Java has no solution/cache knobs --
159
+ accepted for the shared interface and ignored)."""
160
+ s = sync_at(writer, source, target_sha, project_name=project_name, repo_uri=repo_uri, ref=ref)
161
+ return LanguageIngestResult(
162
+ nodes_added=s.nodes_added,
163
+ nodes_updated=s.nodes_updated,
164
+ nodes_removed=s.nodes_removed,
165
+ edges_added=s.edges_added,
166
+ edges_updated=s.edges_updated,
167
+ edges_removed=s.edges_removed,
168
+ files_parsed=s.files_parsed,
169
+ files_cached=s.files_cached,
170
+ commit_sha=s.commit_sha,
171
+ elapsed_seconds=s.elapsed_seconds,
172
+ )
173
+
174
+
175
+ # The GitLanguage is registered by the import-light plugin.py (the entry-point target), whose
176
+ # lazy `sync` thunk calls `_git_language_sync` above -- so importing this tree-sitter engine
177
+ # module is deferred until a source actually contains Java files.
@@ -0,0 +1,14 @@
1
+ """tree-sitter-java Language/Parser setup, in one place so file_parser.py and tests always
2
+ get the exact same configured parser. Like tree-sitter-c/-c-sharp, it ships a pre-built PyPI
3
+ package -- no codegen/vendoring (contrast PL/SQL's vendored ANTLR grammar)."""
4
+
5
+ from __future__ import annotations
6
+
7
+ import tree_sitter_java as tsj
8
+ from tree_sitter import Language, Parser
9
+
10
+ LANGUAGE = Language(tsj.language())
11
+
12
+
13
+ def new_parser() -> Parser:
14
+ return Parser(LANGUAGE)
@@ -0,0 +1,74 @@
1
+ """Canonical id scheme for the Java graph, mirroring the C# ingestor's (Java and C# share the
2
+ same shape: a package/namespace tier over types-with-members). A future deep (JDT/javac) engine
3
+ would key nodes by these same functions, so its output stays interchangeable in one graph --
4
+ the id-parity the C#/Python/C ingestors rely on.
5
+
6
+ Ids embed names/positions and, for overload disambiguation, parameter *type* text -- never
7
+ resolved/inferred types (the id-stability rule)."""
8
+
9
+ from __future__ import annotations
10
+
11
+ _KIND_SLUG = {"Class": "class", "Interface": "interface", "Enum": "enum", "Record": "record"}
12
+
13
+
14
+ def project_id(project_name: str) -> str:
15
+ return f"java://{project_name}"
16
+
17
+
18
+ def module_id(proj_id: str, module: str) -> str:
19
+ """A Maven/Gradle module (subproject) -- the per-file scope root over the package tier, keyed by
20
+ its path-derived name (see javamod.module_for_path). A single-module/root project uses the
21
+ project name as the module name."""
22
+ return f"{proj_id}/module/{module}"
23
+
24
+
25
+ def package_id(scope_id: str, dotted: str) -> str:
26
+ """`scope_id` is the containing module_id (every package now nests under its module, so two
27
+ modules' identically-named packages stay distinct)."""
28
+ return f"{scope_id}/package/{dotted.lower()}"
29
+
30
+
31
+ def file_id(proj_id: str, rel_path: str) -> str:
32
+ return f"{proj_id}/file/{rel_path.replace(chr(92), '/').lstrip('./')}"
33
+
34
+
35
+ def _arity(type_parameters: list[str]) -> str:
36
+ # `Foo` vs `Foo<T,U>` -> distinct ids (a generic and its raw-name twin can't collide).
37
+ return f"`{len(type_parameters)}" if type_parameters else ""
38
+
39
+
40
+ def type_id(scope_id: str, kind: str, name: str, type_parameters: list[str]) -> str:
41
+ """`scope_id` is the containing package_id / project_id (top-level) or the parent type_id
42
+ (nested)."""
43
+ return f"{scope_id}.{_KIND_SLUG[kind]}.{name.lower()}{_arity(type_parameters)}"
44
+
45
+
46
+ def method_id(owner_type_id: str, name: str, param_types: list[str]) -> str:
47
+ signature = ",".join((t or "").lower() for t in param_types)
48
+ return f"{owner_type_id}.method.{name.lower()}({signature})"
49
+
50
+
51
+ def field_id(owner_type_id: str, name: str) -> str:
52
+ return f"{owner_type_id}.field.{name.lower()}"
53
+
54
+
55
+ def parameter_id(owner_id: str, position: int, name: str) -> str:
56
+ return f"{owner_id}.param.{position}.{name.lower()}"
57
+
58
+
59
+ def enum_member_id(enum_type_id: str, name: str) -> str:
60
+ return f"{enum_type_id}.member.{name.lower()}"
61
+
62
+
63
+ # -- cross-repo linkage (ADR 0004) -------------------------------------------------------
64
+ # Project-INDEPENDENT key for an externally-visible method, stored as the `linkage_key`
65
+ # property on real definitions and as the id of the placeholder that stands in for an
66
+ # unresolved call. `qualified_name` is the callee as a consumer would name it -- the owning
67
+ # type's fully-qualified name plus the member, NAME-based (never parameter types, which a
68
+ # caller can't know): e.g. `com.acme.Billing#charge` (a constructor uses the type's simple
69
+ # name as the member, so `com.acme.Widget#Widget`). So a `Widget#charge` call in repo A and
70
+ # `com.acme.Billing#charge`'s definition in repo B land on one node when both share a graph.
71
+ # (Distinct from a Method's own project-scoped `id`, which keeps two repos' same-named methods
72
+ # apart -- see ADR 0004 §2.)
73
+ def extern_method_key(qualified_name: str) -> str:
74
+ return f"extern://java/{qualified_name}"