auryn-cpp 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,212 @@
1
+ """Git-tracked (and directory) C++ ingestion: moves a project's C++ 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#/Java/Python
4
+ ingestors (resolution is global -- the namespace-wide type/method/function index and the
5
+ out-of-line member-definition wiring -- so a file-level diff can't tell which untouched files a
6
+ change affects).
7
+
8
+ Fast engine only for now: tree-sitter-cpp streams each C++ blob (no disk materialization, no
9
+ build config) -> RawFile -> resolution.resolve(). A deep libclang pass (template instantiation,
10
+ overload resolution, ADL, precise header linking, cross-TU calls) would be added as the
11
+ GitLanguage's `deep_sync` (see plugin.py). Registered as the `cpp` GitLanguage for the
12
+ multi-language endpoint (core/ingest.py) in both ingest_repository (git) and ingest_directory
13
+ (local)."""
14
+
15
+ from __future__ import annotations
16
+
17
+ import itertools
18
+ import logging
19
+ import time
20
+ from dataclasses import dataclass
21
+
22
+ from auryn.core.parallel import parse_blobs_ordered
23
+ from auryn.core.graph_model import GraphNode
24
+ from auryn.core.graph_sync import stream_apply
25
+ from auryn.core.registry import LanguageIngestResult
26
+ from auryn.ingestors.cpp import resolution
27
+ from auryn.ingestors.cpp.file_parser import parse_source
28
+ from auryn.ingestors.cpp.ids import project_id
29
+ from auryn.ingestors.cpp.plugin import EXCLUDED_DIR_NAMES as _EXCLUDED_DIR_NAMES
30
+ from auryn.core.cpp_headers import HEADER_SUFFIX, is_cpp_header_blob
31
+ from auryn.ingestors.cpp.plugin import FILE_SUFFIXES as _FILE_SUFFIXES
32
+ from auryn.ingestors.cpp.schema import NODE_SCHEMAS
33
+
34
+ logger = logging.getLogger(__name__)
35
+
36
+ # Provenance-format marker stamped on the Project node once a graph has been built with the
37
+ # File-[:DEFINES|DECLARES]->entity provenance the authored incremental engine reads (ADR 0005). A C++
38
+ # graph built by an OLDER Auryn (full-recompute only, NO provenance edges) lacks it; the incremental
39
+ # route is gated on this marker so such a legacy graph does one full recompute first (which stamps it),
40
+ # instead of taking the incremental path against a graph the engine can't scope. Bump on a format change.
41
+ _DELTA_FORMAT = 1
42
+
43
+
44
+ @dataclass
45
+ class SyncStats:
46
+ nodes_added: int = 0
47
+ nodes_updated: int = 0
48
+ nodes_removed: int = 0
49
+ edges_added: int = 0
50
+ edges_updated: int = 0
51
+ edges_removed: int = 0
52
+ commit_sha: str = ""
53
+ elapsed_seconds: float = 0.0
54
+ files_parsed: int = 0
55
+ files_cached: int = 0
56
+
57
+
58
+ def sync_at(writer, source, target_sha: str, project_name: str, repo_uri: str, ref: str | None) -> SyncStats:
59
+ """Recompute the whole C++ subgraph at `target_sha` and delta it onto the graph. `source`
60
+ is duck-typed (GitRepoCache or LocalDirectorySource): only list_files/read_blob used."""
61
+ started = time.monotonic()
62
+ proj_id = project_id(project_name)
63
+
64
+ writer.setup_schema(NODE_SCHEMAS) # brings the graph key into existence before the first read
65
+ current_sha = writer.get_property("Project", {"id": proj_id}, "commit_sha")
66
+ if current_sha == target_sha:
67
+ return SyncStats(commit_sha=target_sha, elapsed_seconds=time.monotonic() - started)
68
+
69
+ # Incremental resync (ADR 0005, authored-shared engine): when a prior graph already exists at a
70
+ # different, reachable commit, move it by processing only the git diff + its graph-derived blast
71
+ # radius (co-contributor / co-member / reverse-dep closures, provenance-scoped read-back, refcount
72
+ # delete-or-demote) instead of recomputing the whole tree -- see incremental.py. Any failure (old
73
+ # commit unreachable, non-diffable source, plain dir) falls back to the full recompute below.
74
+ # Only route incremental when the existing graph carries the provenance format (a legacy graph built
75
+ # by an older Auryn has commit_sha but no DEFINES/DECLARES provenance -> full recompute re-stamps it).
76
+ has_provenance = writer.get_property("Project", {"id": proj_id}, "delta_format") == _DELTA_FORMAT
77
+ if current_sha and current_sha != target_sha and has_provenance:
78
+ incr = _route(writer, source, target_sha, ref, current_sha,
79
+ project_name=project_name, repo_uri=repo_uri)
80
+ if incr is not None:
81
+ return _finish(writer, proj_id, source, incr)
82
+
83
+ entries = [
84
+ (path, blob_sha)
85
+ for suffix in _FILE_SUFFIXES
86
+ for path, blob_sha in source.list_files(target_sha, suffix, set(_EXCLUDED_DIR_NAMES))
87
+ ]
88
+ # `.h` is not in C++'s suffix list (it's C's by default), but a `.h` with C++ constructs IS a C++
89
+ # header -- the dominant case in real C++ (protobuf/LLVM/Chromium use `.h`). Claim those here so the
90
+ # class declared in the header joins its `.cc` definition under one `cpp://` node; the C ingestor
91
+ # skips the same set (see core.cpp_headers / c.git_sync).
92
+ # KNOWN RESIDUAL (narrow; PR #16 review): the save-watcher derives its trigger extensions from
93
+ # registered file_suffixes (core/watcher.py). `.h` reaches it via the C ingestor's suffix list, so a
94
+ # normal (C + C++) install resyncs on `.h` edits. In a C++-ONLY install (no auryn-c), `.h` is in no
95
+ # suffix list, so a save-triggered watcher won't resync an edited C++ `.h` until a manual/commit sync.
96
+ # The robust fix (content-gated `.h` as a first-class C++ suffix) lands with the incremental `.h` glue.
97
+ entries += [
98
+ (path, blob_sha)
99
+ for path, blob_sha in source.list_files(target_sha, HEADER_SUFFIX, set(_EXCLUDED_DIR_NAMES))
100
+ if is_cpp_header_blob(source.read_blob(blob_sha))
101
+ ]
102
+ files = parse_blobs_ordered(
103
+ entries, source.read_blob, parse_source,
104
+ preload=["auryn.ingestors.cpp.file_parser"], logger=logger,
105
+ )
106
+
107
+ project_node = GraphNode(
108
+ "Project", {"id": proj_id}, {"name": project_name, "repo_uri": repo_uri, "commit_sha": target_sha, "ref": ref}
109
+ )
110
+
111
+ def make_target(): # re-iterable: stream_apply runs it once for nodes, once for edges
112
+ return itertools.chain([project_node], resolution.resolve(files, proj_id))
113
+
114
+ return _finish(writer, proj_id, source,
115
+ _apply(writer, proj_id, make_target, target_sha, started, files_parsed=len(files)))
116
+
117
+
118
+ def _route(writer, source, target_sha, ref, current_sha, *, project_name, repo_uri) -> "SyncStats | None":
119
+ """Attempt an incremental resync via the shared engine's git routing (working-tree or bare-clone
120
+ producer); return SyncStats or None to fall back to the full recompute. C++'s CPP_SPEC sets
121
+ `provenance_rels`, so route_incremental dispatches to the authored-shared engine."""
122
+ from auryn.core.incremental_scoped import route_incremental
123
+ from auryn.ingestors.cpp.incremental import CPP_SPEC
124
+
125
+ s = route_incremental(
126
+ writer, CPP_SPEC, source, target_sha, ref, current_sha,
127
+ project_name=project_name, repo_uri=repo_uri, logger=logger,
128
+ )
129
+ if s is None:
130
+ return None
131
+ return SyncStats(
132
+ nodes_added=s.nodes_added, nodes_updated=s.nodes_updated, nodes_removed=s.nodes_removed,
133
+ edges_added=s.edges_added, edges_updated=s.edges_updated, edges_removed=s.edges_removed,
134
+ commit_sha=s.commit_sha, elapsed_seconds=s.elapsed_seconds,
135
+ files_parsed=s.files_parsed, files_cached=s.files_cached,
136
+ )
137
+
138
+
139
+ def _finish(writer, proj_id: str, source, result: SyncStats) -> SyncStats:
140
+ """After any non-short-circuit sync, record the working-tree base for the next save-triggered
141
+ incremental resync (a no-op for git/plain-dir sources)."""
142
+ from auryn.core.incremental_scoped import stamp_worktree
143
+ from auryn.core.local_source import WorkingTreeSource
144
+
145
+ if isinstance(source, WorkingTreeSource):
146
+ # Stamp `.h` too (not just _FILE_SUFFIXES): since the incremental engine now claims C++-content
147
+ # `.h` headers, a dirty header edit must be remembered as a dirty path -- otherwise reverting an
148
+ # uncommitted `.h` edit back to HEAD leaves no git diff AND no stamped path, so the next
149
+ # save-triggered resync would never reprocess it and the graph would keep the edited version.
150
+ stamp_worktree(writer, proj_id, source, _FILE_SUFFIXES + (HEADER_SUFFIX,))
151
+ # Mark the graph as carrying the provenance format (gates the incremental route; see _DELTA_FORMAT).
152
+ # A side-channel prop set after the Project node is written -- never part of its diffed fingerprint.
153
+ writer.query("MATCH (p:Project {id: $id}) SET p.delta_format = $v", {"id": proj_id, "v": _DELTA_FORMAT})
154
+ return result
155
+
156
+
157
+ def _apply(writer, proj_id: str, make_target, target_sha: str, started: float, files_parsed: int) -> SyncStats:
158
+ # Cross-repo reconciliation (ADR 0004): fold placeholder<->definer pairs among the linkages
159
+ # this ingest touched -- targeted index seeks, no scan. No-op unless the graph holds >1 repo.
160
+ from auryn.core.linkage import reconcile_linkages
161
+
162
+ # stream_apply writes the delta without materialising the target graph, and returns the
163
+ # linkage strings collected inline (see graph_sync.stream_apply / core.linkage).
164
+ labels = [s.label for s in NODE_SCHEMAS]
165
+ stats, reals, placeholders = stream_apply(writer, proj_id, labels, make_target)
166
+ reconcile_linkages(writer, reals, placeholders)
167
+
168
+ return SyncStats(
169
+ nodes_added=stats.nodes_added,
170
+ nodes_updated=stats.nodes_updated,
171
+ nodes_removed=stats.nodes_removed,
172
+ edges_added=stats.edges_added,
173
+ edges_updated=stats.edges_updated,
174
+ edges_removed=stats.edges_removed,
175
+ commit_sha=target_sha,
176
+ elapsed_seconds=time.monotonic() - started,
177
+ files_parsed=files_parsed,
178
+ files_cached=0,
179
+ )
180
+
181
+
182
+ def _git_language_sync(
183
+ writer,
184
+ source,
185
+ target_sha: str,
186
+ *,
187
+ repo_uri: str,
188
+ project_name: str,
189
+ solution_name: str | None,
190
+ ref: str | None,
191
+ cache_root=None,
192
+ ) -> LanguageIngestResult:
193
+ """GitLanguage adapter for the multi-language endpoint (C++ has no solution/cache knobs --
194
+ accepted for the shared interface and ignored)."""
195
+ s = sync_at(writer, source, target_sha, project_name=project_name, repo_uri=repo_uri, ref=ref)
196
+ return LanguageIngestResult(
197
+ nodes_added=s.nodes_added,
198
+ nodes_updated=s.nodes_updated,
199
+ nodes_removed=s.nodes_removed,
200
+ edges_added=s.edges_added,
201
+ edges_updated=s.edges_updated,
202
+ edges_removed=s.edges_removed,
203
+ files_parsed=s.files_parsed,
204
+ files_cached=s.files_cached,
205
+ commit_sha=s.commit_sha,
206
+ elapsed_seconds=s.elapsed_seconds,
207
+ )
208
+
209
+
210
+ # The GitLanguage is registered by the import-light plugin.py (the entry-point target), whose
211
+ # lazy `sync` thunk calls `_git_language_sync` above -- so importing this tree-sitter engine
212
+ # module is deferred until a source actually contains C++ files.
@@ -0,0 +1,14 @@
1
+ """tree-sitter-cpp Language/Parser setup, in one place so file_parser.py and tests always get
2
+ the exact same configured parser. Like tree-sitter-c/-java, tree-sitter-cpp ships a pre-built
3
+ PyPI package -- no codegen/vendoring (contrast PL/SQL's vendored ANTLR grammar)."""
4
+
5
+ from __future__ import annotations
6
+
7
+ import tree_sitter_cpp as tscpp
8
+ from tree_sitter import Language, Parser
9
+
10
+ LANGUAGE = Language(tscpp.language())
11
+
12
+
13
+ def new_parser() -> Parser:
14
+ return Parser(LANGUAGE)
@@ -0,0 +1,80 @@
1
+ """Canonical id scheme for the C++ graph.
2
+
3
+ C++ is the structural union of the C ingestor (free functions, structs/unions/enums, macros,
4
+ includes) and the Java ingestor (a namespace tier over types-with-members, a class hierarchy).
5
+ The ids reflect that: a `Namespace` tier (like Java's Package / C#'s Namespace) scopes types
6
+ and free functions; types scope methods/fields; overloads and templates are disambiguated by
7
+ parameter *type* text and template *arity* respectively, so `foo()`/`foo(int)` and
8
+ `Box`/`Box<T>` never collide. A future deep (libclang) engine would key nodes by these same
9
+ functions, so its output stays interchangeable in one graph -- the id-parity the
10
+ C#/Python/C/Java ingestors rely on.
11
+
12
+ Ids embed names/positions and, for disambiguation, parameter *type* text and template arity --
13
+ never resolved/inferred types (the id-stability rule)."""
14
+
15
+ from __future__ import annotations
16
+
17
+ _KIND_SLUG = {"Class": "class", "Struct": "struct", "Union": "union", "Enum": "enum"}
18
+
19
+
20
+ def project_id(project_name: str) -> str:
21
+ return f"cpp://{project_name}"
22
+
23
+
24
+ def namespace_id(proj_id: str, qualified: str) -> str:
25
+ # `qualified` is the `::`-joined namespace path, e.g. "geo::detail".
26
+ return f"{proj_id}/namespace/{qualified.lower()}"
27
+
28
+
29
+ def file_id(proj_id: str, rel_path: str) -> str:
30
+ return f"{proj_id}/file/{rel_path.replace(chr(92), '/').lstrip('./')}"
31
+
32
+
33
+ def _arity(type_parameters: list[str]) -> str:
34
+ # `Box` vs `Box<T,U>` -> distinct ids (a template and its raw-name twin can't collide).
35
+ return f"`{len(type_parameters)}" if type_parameters else ""
36
+
37
+
38
+ def type_id(scope_id: str, kind: str, name: str, type_parameters: list[str]) -> str:
39
+ """`scope_id` is the containing namespace_id / project_id (top-level) or the parent type_id
40
+ (nested)."""
41
+ return f"{scope_id}.{_KIND_SLUG[kind]}.{name.lower()}{_arity(type_parameters)}"
42
+
43
+
44
+ def method_id(owner_type_id: str, name: str, param_types: list[str]) -> str:
45
+ signature = ",".join((t or "").lower() for t in param_types)
46
+ return f"{owner_type_id}.method.{name.lower()}({signature})"
47
+
48
+
49
+ def function_id(scope_id: str, name: str, param_types: list[str]) -> str:
50
+ """A free function, keyed by its scope (namespace/project) + name + parameter types (C++
51
+ allows overloading, so the parameter types are part of the identity)."""
52
+ signature = ",".join((t or "").lower() for t in param_types)
53
+ return f"{scope_id}.func.{name.lower()}({signature})"
54
+
55
+
56
+ def field_id(owner_type_id: str, name: str) -> str:
57
+ return f"{owner_type_id}.field.{name.lower()}"
58
+
59
+
60
+ def parameter_id(owner_id: str, position: int, name: str) -> str:
61
+ return f"{owner_id}.param.{position}.{name.lower()}"
62
+
63
+
64
+ def enum_member_id(enum_type_id: str, name: str) -> str:
65
+ return f"{enum_type_id}.member.{name.lower()}"
66
+
67
+
68
+ # -- preprocessor: file-local (mirrors the C ingestor's macro scoping) --------------------
69
+ def macro_id(a_file_id: str, name: str) -> str:
70
+ return f"{a_file_id}.macro.{name}"
71
+
72
+
73
+ # -- cross-repo linkage (ADR 0004) -------------------------------------------------------
74
+ # Project-independent key for a free/namespaced function, name-based (no param types -- a
75
+ # consumer can't know an overload's types): `extern://cpp/<ns::name>` or `extern://cpp/<name>`.
76
+ # Stored as `linkage_key` on real definitions and as the id of the placeholder standing in for an
77
+ # unresolved call, so `mylib::compute` in repo B and a `mylib::compute()` call in repo A land on
78
+ # one node when both share a graph.
79
+ def extern_function_key(qualified_name: str) -> str:
80
+ return f"extern://cpp/{qualified_name}"
@@ -0,0 +1,332 @@
1
+ """C++ binding for the AUTHORED-SHARED incremental resync engine (core/incremental_scoped.py,
2
+ ADR 0005).
3
+
4
+ C++ is the structural union of C and Java (see resolution.py / schema.py), so its incremental spec is
5
+ too: from Java, a `Namespace` aggregation tier over types with methods/fields and an EXTENDS hierarchy;
6
+ from C, free `Function`s, file-scoped `Macro`s, and File->File `INCLUDES` + the extern:// call-placeholder
7
+ model. Almost every entity is program-global (keyed `cpp://<proj>/namespace/.../class.X/method.Y`, NOT under
8
+ a file), shared across the header that DECLARES it and the .cc that DEFINES it; the per-file ownership
9
+ handle is the `File-[:DEFINES|DECLARES]->entity` edge (added in resolution.py, uniform with C/Go/Java).
10
+
11
+ The one feature no other authored language has is OUT-OF-LINE method definitions: a method is declared in a
12
+ class body (a .h) but defined `Class::method(){..}` in a separate .cc. So a single method node is co-authored
13
+ by two different files. Both must be re-authored together on any resync, which the engine's two co-member
14
+ closures guarantee: `type_member_rels` (forward: a type's .h changes -> pull the method's .cc) and
15
+ `member_owner_rels` (reverse: the .cc changes -> pull the type's .h). With both, a method's complete
16
+ contributor set is always in the emit set, so it is never sparsely re-emitted -- no decl-only handling is
17
+ needed for methods (only for forward-declared TYPES and free-function PROTOTYPES, as in C).
18
+
19
+ Correctness (incremental == full recompute, node/edge-identical) is enforced by the language-agnostic gate
20
+ (tests/sync/test_delta_differential.py + test_delta_cross_repo.py)."""
21
+
22
+ from __future__ import annotations
23
+
24
+ from auryn.core.cpp_headers import HEADER_SUFFIX, is_cpp_header_blob
25
+ from auryn.core.graph_client import GraphWriter, semantic_label
26
+ from auryn.core.graph_model import GraphNode
27
+ from auryn.core.incremental_scoped import ChangeSet, ScopedSpec, incremental_sync_authored
28
+ from auryn.ingestors.cpp import ids, resolution
29
+ from auryn.ingestors.cpp.file_parser import parse_source
30
+ from auryn.ingestors.cpp.plugin import EXCLUDED_DIR_NAMES as _EXCLUDED_DIR_NAMES
31
+ from auryn.ingestors.cpp.plugin import FILE_SUFFIXES as _FILE_SUFFIXES
32
+ from auryn.ingestors.cpp.schema import NODE_SCHEMAS
33
+
34
+ __all__ = ["ChangeSet", "CPP_SPEC", "read_cpp_index", "incremental_cpp_sync"]
35
+
36
+ # Edge classification for the engine (see core/incremental_scoped.read_authored_fingerprints):
37
+ # - provenance (File->entity ownership handle): DEFINES (definitions) / DECLARES (header-only).
38
+ # - lateral (source-owned): CALLS + DEPENDS_ON + EXTENDS + INCLUDES + DEFINED_IN (type->File, re-emitted
39
+ # with its type).
40
+ # - containment (target-owned): the structural spine.
41
+ # - symbol-ref (reverse-dep closure): a change to a type/method/function affects its callers / subclasses
42
+ # / dependents -> CALLS + DEPENDS_ON + EXTENDS.
43
+ _PROVENANCE_RELS = ("DEFINES", "DECLARES")
44
+ _LATERAL_RELS = ("CALLS", "DEPENDS_ON", "EXTENDS", "INCLUDES", "DEFINED_IN")
45
+ _CONTAINMENT_RELS = ("HAS_NAMESPACE", "HAS_SUB_NAMESPACE", "HAS_FILE", "HAS_TYPE", "HAS_NESTED_TYPE",
46
+ "HAS_FUNCTION", "HAS_METHOD", "HAS_FIELD", "HAS_PARAMETER", "HAS_ENUM_MEMBER")
47
+ _SYMBOL_REF_RELS = ("CALLS", "DEPENDS_ON", "EXTENDS")
48
+ _TARGETABLE = ("Class", "Struct", "Union", "Enum", "Method", "Function")
49
+ _TYPE_LABEL_PRED = "(t:Class OR t:Struct OR t:Union OR t:Enum)"
50
+
51
+
52
+ def _scope_key(path: str) -> str:
53
+ """A file's stable scope key = normalized path -- exactly what `File.path`/`file_id` use."""
54
+ return path.replace("\\", "/").lstrip("./")
55
+
56
+
57
+ def _cpp_project_node(project_name, repo_uri, proj_id, target_sha, ref) -> GraphNode:
58
+ return GraphNode("Project", {"id": proj_id},
59
+ {"name": project_name, "repo_uri": repo_uri, "commit_sha": target_sha, "ref": ref})
60
+
61
+
62
+ def _namespace_of(qualified_name: str | None, name: str) -> str:
63
+ """The `::`-joined namespace of a qualified_name (`a::b::X` -> `a::b`), "" for global scope."""
64
+ qn = qualified_name if qualified_name is not None else name
65
+ return qn.rsplit("::", 1)[0] if "::" in qn else ""
66
+
67
+
68
+ def _cpp_referenced_names(rf) -> set[str]:
69
+ """Simple names an emit file could resolve cross-file: call names, base names, and the identifiers
70
+ in method/function/field/param/return type text. Only bounds the index seed; read_cpp_index seeds
71
+ the whole non-emit index, so over-collecting is harmless."""
72
+ names: set[str] = set()
73
+
74
+ def add_type_text(txt):
75
+ names.update(resolution._referenced_names(txt))
76
+
77
+ for rt in rf.types:
78
+ _collect_type_names(rt, names, add_type_text)
79
+ for fn in rf.functions:
80
+ add_type_text(fn.return_type)
81
+ for p in fn.params:
82
+ add_type_text(p.type)
83
+ names.update(c.name for c in fn.calls)
84
+ names.update(c.scope for c in fn.calls if c.scope)
85
+ for md in rf.member_defs:
86
+ if md.owner_name:
87
+ names.add(md.owner_name)
88
+ add_type_text(md.return_type)
89
+ for p in md.params:
90
+ add_type_text(p.type)
91
+ names.update(c.name for c in md.calls)
92
+ names.update(c.scope for c in md.calls if c.scope)
93
+ return {n for n in names if n}
94
+
95
+
96
+ def _collect_type_names(rt, names: set[str], add_type_text) -> None:
97
+ for b in rt.bases:
98
+ names.add(b.name)
99
+ for m in rt.methods:
100
+ add_type_text(m.return_type)
101
+ for p in m.params:
102
+ add_type_text(p.type)
103
+ names.update(c.name for c in m.calls)
104
+ names.update(c.scope for c in m.calls if c.scope)
105
+ for f in rt.fields:
106
+ add_type_text(f.type)
107
+ for nested in rt.nested_types:
108
+ _collect_type_names(nested, names, add_type_text)
109
+
110
+
111
+ def _cpp_defined_symbol_ids(raw, proj_id: str) -> list[tuple[str, str]]:
112
+ """(node_id, label) of the program-global symbols this file defines, computed from the parse via the
113
+ SAME id functions the emitter uses -- types, their in-class methods, and free functions. Drives the v2
114
+ reverse-dep narrowing. OUT-OF-LINE method definitions (whose owner type is cross-file and so not
115
+ resolvable from this file alone) are deliberately OMITTED: that only makes the narrowing more
116
+ conservative (an out-of-line method reads as "removed", harmlessly re-resolving its callers and pulling
117
+ its class's file -- which the member_owner closure pulls anyway), never less safe."""
118
+ out: list[tuple[str, str]] = []
119
+ entries: list = []
120
+ for rt in raw.types:
121
+ resolution._flatten(rt, "", proj_id, None, entries)
122
+ for e in entries:
123
+ out.append((e.type_id, e.kind))
124
+ for m in e.raw_type.methods:
125
+ out.append((ids.method_id(e.type_id, m.name, [p.type for p in m.params]), "Method"))
126
+ for fn in raw.functions:
127
+ out.append((resolution._make_func_rec(fn, proj_id).function_id, "Function"))
128
+ return out
129
+
130
+
131
+ def _cpp_satisfied_linkage_keys(raws) -> set[str]:
132
+ """The extern:// linkages the emit set's free-function definitions can satisfy: an untouched caller
133
+ pointing at `extern://cpp/<qualified>` re-binds when an emit file defines that free function. Mirrors
134
+ _emit_function's linkage_key exactly. (Methods carry no linkage_key -- C++ cross-repo calls are
135
+ free/namespaced functions only, as in resolution._external_free_call.)"""
136
+ out: set[str] = set()
137
+ for rf in raws:
138
+ for fn in rf.functions:
139
+ qualified = f"{fn.namespace}::{fn.name}" if fn.namespace else fn.name
140
+ out.add(ids.extern_function_key(qualified))
141
+ return out
142
+
143
+
144
+ def _cpp_displaced_emit_files(writer: GraphWriter, proj_id: str, raws) -> set[str]:
145
+ """Extra emit files a PARSE-DRIVEN lookup finds that the graph-provenance closures miss because the
146
+ emit file is BRAND NEW (its own edges aren't in the graph yet, ADR 0005). The C++ out-of-line case: a
147
+ new .cc with `Class::method(){..}` -- `_comember_owner_file_ids` can't pull `Class`'s file because it
148
+ keys on the new .cc's not-yet-existing provenance. Pull the owner type's WHOLE contributor set: the
149
+ file(s) that DEFINE/DECLARE the type AND the file(s) defining its OTHER methods. Pulling just the header
150
+ is not enough -- re-authoring the type from its header alone would downgrade its other out-of-line
151
+ methods (defined in .cc files not pulled) to declaration-only. This replicates what the co-member
152
+ fixpoint does for an existing file; it must be explicit here because a brand-new .cc has no provenance
153
+ to seed that fixpoint. Returns File ids; the engine parses + adds them to the emit set. A no-op for the
154
+ common edit (no new out-of-line def). Every query is an id-index seek.
155
+
156
+ KNOWN LIMITATION (documented, not handled): adding a BRAND-NEW file that re-defines a free function an
157
+ existing file already defines can pick a different multiply-defined winner than a full recompute (the
158
+ co-definer closure keys on the new file's absent provenance). This is an ODR violation in C++ (two
159
+ external definitions of one free function don't link), so it is pathological; the normal multi-variant
160
+ case where the colliding files already EXIST is handled by the graph co-definer closure + path-sorting."""
161
+ lo, hi = proj_id + "/", proj_id + "/" + chr(0xFFFF)
162
+ out: set[str] = set()
163
+ owner_names = sorted({md.owner_name for raw in raws for md in raw.member_defs if md.owner_name})
164
+ if owner_names:
165
+ for (fid,) in writer.ro_query(
166
+ f"MATCH (f:File)-[:DEFINES|DECLARES]->(t) WHERE t.name IN $names AND {_TYPE_LABEL_PRED} "
167
+ f"AND t.id >= $lo AND t.id < $hi RETURN DISTINCT f.id",
168
+ {"names": owner_names, "lo": lo, "hi": hi},
169
+ ).result_set:
170
+ out.add(str(fid))
171
+ for (fid,) in writer.ro_query(
172
+ f"MATCH (f:File)-[:DEFINES]->(m:Method), (t)-[:HAS_METHOD]->(m) "
173
+ f"WHERE t.name IN $names AND {_TYPE_LABEL_PRED} AND t.id >= $lo AND t.id < $hi "
174
+ f"RETURN DISTINCT f.id",
175
+ {"names": owner_names, "lo": lo, "hi": hi},
176
+ ).result_set:
177
+ out.add(str(fid))
178
+ # Co-DECLARER pull: for each TYPE the emit set defines, pull the file(s) that merely DECLARE it (a
179
+ # `class X;` forward declaration in another header). DEFINED_IN (type->File) is a lateral multi-file
180
+ # edge -- a type declared in a header AND defined in a .cc has one per file -- and the read-back claims
181
+ # ALL of them once the type is owned. The co-DEFINER closure is DEFINES-keyed and so misses a pure
182
+ # forward-declarer; without this, editing the DEFINER .cc re-emits only its own DEFINED_IN and
183
+ # compute_delta drops the declarer's (and can strand the type's other members). A no-op unless the
184
+ # emit set defines a type some other file forward-declares.
185
+ # Pull each such type's WHOLE contributor set: its forward-declarer header(s) AND the file(s) defining
186
+ # its out-of-line methods. Pulling only the declarer isn't enough -- re-authoring the type without its
187
+ # method-definer .cc would merge the methods from their DECLARATION (decl param NAMES), while a full
188
+ # recompute uses the DEFINITION's (so a param `batch` vs an unnamed `arg3` strands a Parameter node).
189
+ type_ids = [sid for raw in raws for sid, lbl in _cpp_defined_symbol_ids(raw, proj_id)
190
+ if lbl in ("Class", "Struct", "Union", "Enum")]
191
+ for i in range(0, len(type_ids), 1000):
192
+ chunk = type_ids[i:i + 1000]
193
+ for (fid,) in writer.ro_query(
194
+ "MATCH (f:File)-[:DECLARES]->(t) WHERE t.id IN $ids RETURN DISTINCT f.id", {"ids": chunk},
195
+ ).result_set:
196
+ out.add(str(fid))
197
+ for (fid,) in writer.ro_query(
198
+ "MATCH (f:File)-[:DEFINES]->(m:Method)<-[:HAS_METHOD]-(t) WHERE t.id IN $ids "
199
+ "RETURN DISTINCT f.id", {"ids": chunk},
200
+ ).result_set:
201
+ out.add(str(fid))
202
+ return out
203
+
204
+
205
+ def read_cpp_index(writer: GraphWriter, proj_id: str, exclude_keys: set[str], names: set[str]) -> resolution.CppGraphIndex:
206
+ """Reconstruct C++'s resolution tables from the graph for every file EXCEPT `exclude_keys` (the emit +
207
+ removed set), so `resolve_incremental` resolves an emit file's cross-file EXTENDS/DEPENDS_ON/CALLS/
208
+ #include against the surviving project without re-parsing it. Every query is an id-index seek."""
209
+ idx = resolution.CppGraphIndex()
210
+ lo, hi = proj_id + "/", proj_id + "/" + chr(0xFFFF)
211
+ exclude_file_ids = {ids.file_id(proj_id, k) for k in exclude_keys}
212
+
213
+ # Surviving files' normalized full path -> File id, for #include resolution. NO basename collapse here:
214
+ # a basename shared by a surviving file and an emit file must be judged ambiguous over the UNION, so
215
+ # resolve_incremental collapses basenames over seed+emit together (see resolution._collapse_basenames).
216
+ full: dict[str, str] = {}
217
+ seed_file_ids: list[str] = []
218
+ for fid, path in writer.ro_query(
219
+ "MATCH (f:File) WHERE f.id >= $lo AND f.id < $hi RETURN f.id, f.path", {"lo": lo, "hi": hi}
220
+ ).result_set:
221
+ if str(fid) in exclude_file_ids:
222
+ continue
223
+ seed_file_ids.append(str(fid))
224
+ full[resolution._norm(str(path))] = str(fid)
225
+ idx.include_fullpaths = full
226
+
227
+ if not seed_file_ids:
228
+ return idx
229
+
230
+ # Type stubs (name -> [_TypeStub]) for EXTENDS/DEPENDS_ON/call-receiver resolution.
231
+ for tid, label, tname, qn in writer.ro_query(
232
+ f"MATCH (file:File)-[:DEFINES|DECLARES]->(t) WHERE file.id IN $fids AND {_TYPE_LABEL_PRED} "
233
+ f"RETURN DISTINCT t.id, {semantic_label('t')}, t.name, t.qualified_name", {"fids": seed_file_ids},
234
+ ).result_set:
235
+ tname = str(tname)
236
+ idx.type_index.setdefault(tname, []).append(
237
+ resolution._TypeStub(str(tid), str(label), tname, _namespace_of(qn, tname)))
238
+
239
+ # Method entries (name -> [_MethodIndexEntry], incl constructors) for CALLS / `new X()` resolution.
240
+ for mname, owner_id, mid, kind, owner_qn in writer.ro_query(
241
+ "MATCH (file:File)-[:DEFINES|DECLARES]->(m:Method), (t)-[:HAS_METHOD]->(m) "
242
+ "WHERE file.id IN $fids RETURN DISTINCT m.name, t.id, m.id, m.kind, t.qualified_name",
243
+ {"fids": seed_file_ids},
244
+ ).result_set:
245
+ idx.method_index.setdefault(str(mname), []).append(
246
+ resolution._MethodIndexEntry(str(owner_id), str(mid), str(kind), _namespace_of(owner_qn, "")))
247
+
248
+ # Free-function stubs (name -> [_FuncStub]) for free-function CALLS resolution.
249
+ for fname, fnid, qn in writer.ro_query(
250
+ "MATCH (file:File)-[:DEFINES|DECLARES]->(fn:Function) WHERE file.id IN $fids "
251
+ "RETURN DISTINCT fn.name, fn.id, fn.qualified_name", {"fids": seed_file_ids},
252
+ ).result_set:
253
+ fname = str(fname)
254
+ idx.function_index.setdefault(fname, []).append(
255
+ resolution._FuncStub(str(fnid), _namespace_of(qn, fname)))
256
+
257
+ # ids DEFINED (not merely declared) by a surviving file: a forward-decl / prototype in the emit set
258
+ # for one of these emits only its DECLARES provenance, never a sparse node (ADR 0005 ownership).
259
+ idx.defined_type_ids = frozenset(
260
+ str(tid) for (tid,) in writer.ro_query(
261
+ f"MATCH (file:File)-[:DEFINES]->(t) WHERE file.id IN $fids AND {_TYPE_LABEL_PRED} "
262
+ f"RETURN DISTINCT t.id", {"fids": seed_file_ids}).result_set)
263
+ idx.defined_function_ids = frozenset(
264
+ str(fnid) for (fnid,) in writer.ro_query(
265
+ "MATCH (file:File)-[:DEFINES]->(fn:Function) WHERE file.id IN $fids "
266
+ "RETURN DISTINCT fn.id", {"fids": seed_file_ids}).result_set)
267
+ return idx
268
+
269
+
270
+ def _cpp_claims_path(path: str, read_blob) -> bool:
271
+ """C++ owns `.cpp/.cc/.hpp/...` always, and a `.h` ONLY if its content is C++ (header routing, see
272
+ core.cpp_headers). Mirrors the full-ingest walk in git_sync (which claims a C++-content `.h`) and C's
273
+ inverse disown, so a header's owner is identical on a full ingest and an incremental resync -- and,
274
+ because `.h` is in CPP_SPEC.file_suffixes below, the incremental diff actually SEES a changed C++ `.h`
275
+ (without this glue the C++ incremental resync would never re-ingest an edited class header)."""
276
+ if path.endswith(HEADER_SUFFIX): # ".h" -- ambiguous C/C++; C++ claims only the C++-content ones
277
+ return is_cpp_header_blob(read_blob())
278
+ return True
279
+
280
+
281
+ CPP_SPEC = ScopedSpec(
282
+ language="cpp",
283
+ node_schemas=tuple(NODE_SCHEMAS),
284
+ node_labels=tuple(s.label for s in NODE_SCHEMAS),
285
+ # `.h` is added so the incremental diff detects a changed C++-content header (header routing sends it
286
+ # to C++); `claims_path` then keeps only the C++-content `.h` (a C-content `.h` is disowned, exactly
287
+ # as the full walk + the C ingestor's inverse do), so full-ingest and delta agree on ownership.
288
+ file_suffixes=tuple(_FILE_SUFFIXES) + (HEADER_SUFFIX,),
289
+ claims_path=_cpp_claims_path,
290
+ excluded_dir_names=frozenset(_EXCLUDED_DIR_NAMES),
291
+ symbol_ref_rels=_SYMBOL_REF_RELS,
292
+ lateral_rels=_LATERAL_RELS,
293
+ containment_rels=_CONTAINMENT_RELS,
294
+ targetable_labels=_TARGETABLE,
295
+ import_rel="INCLUDES",
296
+ import_target_labels=("File",),
297
+ project_id=ids.project_id,
298
+ scope_id_for_path=ids.file_id,
299
+ scope_key_for_path=_scope_key,
300
+ parse=parse_source,
301
+ # tree-sitter-cpp recovers from errors (best-effort partial), identical in both engines (matches C).
302
+ is_broken=lambda rf: False,
303
+ referenced_names=_cpp_referenced_names,
304
+ read_index=read_cpp_index,
305
+ resolve_incremental=resolution.resolve_incremental,
306
+ project_node=_cpp_project_node,
307
+ satisfied_linkage_keys=_cpp_satisfied_linkage_keys,
308
+ # A BRAND-NEW .cc defining an existing class's method (or redefining an existing free function) has no
309
+ # graph provenance yet, so the graph-keyed co-member/co-definer closures miss it; this parse-driven
310
+ # hook pulls the owner type's file + any existing co-definer so the out-of-line method merges and a
311
+ # multiply-defined symbol reduces to the same winner as a full recompute (PR #18 review).
312
+ displaced_caller_files=_cpp_displaced_emit_files,
313
+ provenance_rels=_PROVENANCE_RELS,
314
+ definition_rels=("DEFINES",), # a header DECLARES; the .cc / class-body DEFINES the data
315
+ linkable_labels=("Function",), # only free functions carry a cross-repo linkage_key (ADR 0004)
316
+ defined_symbol_ids=_cpp_defined_symbol_ids,
317
+ # Out-of-line method defs live in a .cc apart from the class body in a .h -> a method is co-authored by
318
+ # two files. Pull BOTH together on any resync: type_member_rels (type's .h changes -> pull method .cc)
319
+ # and member_owner_rels (the .cc changes -> pull the type's .h). Together a method is always re-authored
320
+ # by its complete contributor set, so it is never sparsely re-emitted.
321
+ type_member_rels=("HAS_METHOD",),
322
+ member_owner_rels=("HAS_METHOD",),
323
+ # Namespaces are an aggregation tier (like Java's Package/Module): id-derived props, co-declared by
324
+ # every file beneath them -> refcount-GC'd, excluded from the co-definer winner closure.
325
+ aggregation_labels=("Namespace",),
326
+ )
327
+
328
+
329
+ def incremental_cpp_sync(writer, source, target_sha, changes, *, project_name, repo_uri, ref=None):
330
+ """Thin wrapper over the shared authored-shared engine (git_sync routes through the same one)."""
331
+ return incremental_sync_authored(writer, CPP_SPEC, source, target_sha, changes,
332
+ project_name=project_name, repo_uri=repo_uri, ref=ref)