intentumdiff-python 0.0.1__py3-none-win_arm64.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.
Files changed (165) hide show
  1. intentumdiff/__init__.py +134 -0
  2. intentumdiff/_differ_gate.py +210 -0
  3. intentumdiff/_differ_presentation.py +786 -0
  4. intentumdiff/_differ_runtime.py +320 -0
  5. intentumdiff/analysis/__init__.py +1 -0
  6. intentumdiff/analysis/compile_commands.py +151 -0
  7. intentumdiff/analysis/cross_file.py +71 -0
  8. intentumdiff/analysis/diagnostics.py +309 -0
  9. intentumdiff/analysis/guardrail_reports.py +254 -0
  10. intentumdiff/analysis/guardrails.py +318 -0
  11. intentumdiff/analysis/invariances.py +1207 -0
  12. intentumdiff/analysis/keyed_profiles.py +25 -0
  13. intentumdiff/analysis/resource_profiles.py +14 -0
  14. intentumdiff/analysis/schema_resolver.py +816 -0
  15. intentumdiff/analysis/text_review.py +46 -0
  16. intentumdiff/analysis/user_schemas.py +430 -0
  17. intentumdiff/assets.py +45 -0
  18. intentumdiff/cache/__init__.py +37 -0
  19. intentumdiff/cache/duckdb_store.py +98 -0
  20. intentumdiff/cache/sqlite_store.py +149 -0
  21. intentumdiff/cache/store.py +190 -0
  22. intentumdiff/cli/__init__.py +199 -0
  23. intentumdiff/cli/_commands.py +2141 -0
  24. intentumdiff/cli/_parser.py +1061 -0
  25. intentumdiff/cli/_shared.py +644 -0
  26. intentumdiff/content_type.py +59 -0
  27. intentumdiff/core/__init__.py +1 -0
  28. intentumdiff/core/commit_differ.py +599 -0
  29. intentumdiff/core/config.py +51 -0
  30. intentumdiff/core/cst_serializer.py +101 -0
  31. intentumdiff/core/diffignore.py +87 -0
  32. intentumdiff/core/index.py +189 -0
  33. intentumdiff/core/indexer.py +792 -0
  34. intentumdiff/core/models.py +837 -0
  35. intentumdiff/differ.py +2195 -0
  36. intentumdiff/github_app.py +287 -0
  37. intentumdiff/intentumdiff_rust_core/__init__.py +7 -0
  38. intentumdiff/intentumdiff_rust_core/ffi.py +8 -0
  39. intentumdiff/intentumdiff_rust_core/intentumdiff_rust_core.dll +0 -0
  40. intentumdiff/invariances/__init__.py +2 -0
  41. intentumdiff/invariances/rules.schema.json +283 -0
  42. intentumdiff/invariances/rules.yaml +349 -0
  43. intentumdiff/live_server.py +1314 -0
  44. intentumdiff/lsp/__init__.py +67 -0
  45. intentumdiff/lsp/client.py +544 -0
  46. intentumdiff/lsp/config.py +96 -0
  47. intentumdiff/lsp/enricher.py +227 -0
  48. intentumdiff/lsp/exceptions.py +27 -0
  49. intentumdiff/lsp/launcher.py +273 -0
  50. intentumdiff/lsp/servers.py +356 -0
  51. intentumdiff/lsp_server/__init__.py +14 -0
  52. intentumdiff/lsp_server/_codelens.py +67 -0
  53. intentumdiff/lsp_server/_diagnostics.py +62 -0
  54. intentumdiff/lsp_server/_handlers.py +175 -0
  55. intentumdiff/lsp_server/server.py +205 -0
  56. intentumdiff/plugins/__init__.py +1 -0
  57. intentumdiff/plugins/adapter.py +397 -0
  58. intentumdiff/plugins/builtins.py +323 -0
  59. intentumdiff/plugins/exceptions.py +93 -0
  60. intentumdiff/plugins/hub.py +1155 -0
  61. intentumdiff/plugins/language_metadata.py +250 -0
  62. intentumdiff/plugins/loader.py +1252 -0
  63. intentumdiff/plugins/registry.py +1079 -0
  64. intentumdiff/plugins/registry.schema.json +99 -0
  65. intentumdiff/plugins/registry_schema.py +280 -0
  66. intentumdiff/plugins/wit/plugin.wit +351 -0
  67. intentumdiff/rust_core.py +2370 -0
  68. intentumdiff/serve/__init__.py +19 -0
  69. intentumdiff/serve/_app.py +485 -0
  70. intentumdiff/serve/_static/index.html +326 -0
  71. intentumdiff/serve/_static/playground.js +567 -0
  72. intentumdiff/sources/__init__.py +1 -0
  73. intentumdiff/sources/base.py +28 -0
  74. intentumdiff/sources/file_source.py +48 -0
  75. intentumdiff/sources/git_source.py +375 -0
  76. intentumdiff/sources/live_buffer_source.py +113 -0
  77. intentumdiff/sources/patch_source.py +126 -0
  78. intentumdiff/sources/string_source.py +44 -0
  79. intentumdiff/testing.py +165 -0
  80. intentumdiff/vcs/__init__.py +37 -0
  81. intentumdiff/vcs/_safe_path.py +50 -0
  82. intentumdiff/vcs/base.py +136 -0
  83. intentumdiff/vcs/git_backend.py +97 -0
  84. intentumdiff/vcs/git_cli.py +100 -0
  85. intentumdiff/vcs/hg_backend.py +94 -0
  86. intentumdiff/vcs/perforce_backend.py +109 -0
  87. intentumdiff/vcs/svn_backend.py +105 -0
  88. intentumdiff/wasm/.gitkeep +2 -0
  89. intentumdiff/wasm/abap_parser.wasm +0 -0
  90. intentumdiff/wasm/adf_parser.wasm +0 -0
  91. intentumdiff/wasm/asciidoc_parser.wasm +0 -0
  92. intentumdiff/wasm/asm_parser.wasm +0 -0
  93. intentumdiff/wasm/assemblyscript_parser.wasm +0 -0
  94. intentumdiff/wasm/astro_parser.wasm +0 -0
  95. intentumdiff/wasm/bash_parser.wasm +0 -0
  96. intentumdiff/wasm/clojure_parser.wasm +0 -0
  97. intentumdiff/wasm/cmake_parser.wasm +0 -0
  98. intentumdiff/wasm/cpp_parser.wasm +0 -0
  99. intentumdiff/wasm/csharp_parser.wasm +0 -0
  100. intentumdiff/wasm/css_parser.wasm +0 -0
  101. intentumdiff/wasm/dart_parser.wasm +0 -0
  102. intentumdiff/wasm/databricks_parser.wasm +0 -0
  103. intentumdiff/wasm/dax_parser.wasm +0 -0
  104. intentumdiff/wasm/delphi_parser.wasm +0 -0
  105. intentumdiff/wasm/dockerfile_parser.wasm +0 -0
  106. intentumdiff/wasm/elixir_parser.wasm +0 -0
  107. intentumdiff/wasm/freebasic_parser.wasm +0 -0
  108. intentumdiff/wasm/generic_parser.wasm +0 -0
  109. intentumdiff/wasm/gitignore_parser.wasm +0 -0
  110. intentumdiff/wasm/go_parser.wasm +0 -0
  111. intentumdiff/wasm/gomod_parser.wasm +0 -0
  112. intentumdiff/wasm/graphql_parser.wasm +0 -0
  113. intentumdiff/wasm/groovy_parser.wasm +0 -0
  114. intentumdiff/wasm/haskell_parser.wasm +0 -0
  115. intentumdiff/wasm/html_parser.wasm +0 -0
  116. intentumdiff/wasm/ini_parser.wasm +0 -0
  117. intentumdiff/wasm/java_parser.wasm +0 -0
  118. intentumdiff/wasm/js_ts_parser.wasm +0 -0
  119. intentumdiff/wasm/json_parser.wasm +0 -0
  120. intentumdiff/wasm/kotlin_parser.wasm +0 -0
  121. intentumdiff/wasm/latex_parser.wasm +0 -0
  122. intentumdiff/wasm/lua_parser.wasm +0 -0
  123. intentumdiff/wasm/make_parser.wasm +0 -0
  124. intentumdiff/wasm/markdown_parser.wasm +0 -0
  125. intentumdiff/wasm/mdx_parser.wasm +0 -0
  126. intentumdiff/wasm/ocaml_parser.wasm +0 -0
  127. intentumdiff/wasm/odin_parser.wasm +0 -0
  128. intentumdiff/wasm/parser_manifest.json +590 -0
  129. intentumdiff/wasm/perl_parser.wasm +0 -0
  130. intentumdiff/wasm/php_parser.wasm +0 -0
  131. intentumdiff/wasm/plsql_parser.wasm +0 -0
  132. intentumdiff/wasm/po_parser.wasm +0 -0
  133. intentumdiff/wasm/postscript_parser.wasm +0 -0
  134. intentumdiff/wasm/powershell_parser.wasm +0 -0
  135. intentumdiff/wasm/proto_parser.wasm +0 -0
  136. intentumdiff/wasm/puppet_parser.wasm +0 -0
  137. intentumdiff/wasm/python_parser.wasm +0 -0
  138. intentumdiff/wasm/qsharp_parser.wasm +0 -0
  139. intentumdiff/wasm/r_parser.wasm +0 -0
  140. intentumdiff/wasm/reasonml_parser.wasm +0 -0
  141. intentumdiff/wasm/ruby_parser.wasm +0 -0
  142. intentumdiff/wasm/rust_parser.wasm +0 -0
  143. intentumdiff/wasm/sas_parser.wasm +0 -0
  144. intentumdiff/wasm/scala_parser.wasm +0 -0
  145. intentumdiff/wasm/scss_parser.wasm +0 -0
  146. intentumdiff/wasm/sql_parser.wasm +0 -0
  147. intentumdiff/wasm/squirrel_parser.wasm +0 -0
  148. intentumdiff/wasm/svelte_parser.wasm +0 -0
  149. intentumdiff/wasm/swift_parser.wasm +0 -0
  150. intentumdiff/wasm/terraform_parser.wasm +0 -0
  151. intentumdiff/wasm/toml_parser.wasm +0 -0
  152. intentumdiff/wasm/tsql_parser.wasm +0 -0
  153. intentumdiff/wasm/vbnet_parser.wasm +0 -0
  154. intentumdiff/wasm/vue_parser.wasm +0 -0
  155. intentumdiff/wasm/wat_parser.wasm +0 -0
  156. intentumdiff/wasm/xml_parser.wasm +0 -0
  157. intentumdiff/wasm/yaml_parser.wasm +0 -0
  158. intentumdiff/wasm/zig_parser.wasm +0 -0
  159. intentumdiff/watcher.py +259 -0
  160. intentumdiff_python-0.0.1.dist-info/METADATA +112 -0
  161. intentumdiff_python-0.0.1.dist-info/RECORD +165 -0
  162. intentumdiff_python-0.0.1.dist-info/WHEEL +4 -0
  163. intentumdiff_python-0.0.1.dist-info/entry_points.txt +80 -0
  164. intentumdiff_python-0.0.1.dist-info/licenses/LICENSE +21 -0
  165. intentumdiff_python-0.0.1.dist-info/sboms/intentumdiff-rust-core.cyclonedx.json +10968 -0
@@ -0,0 +1,101 @@
1
+ """
2
+ intentumdiff.core.cst_serializer
3
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4
+
5
+ Converts a tree-sitter ``Node`` tree into the canonical JSON string consumed
6
+ by parser plugins (``interpret-cst`` mode).
7
+
8
+ Schema (each node object)
9
+ ─────────────────────────
10
+ {
11
+ "type": "<node_type>", // tree-sitter node.type
12
+ "named": true | false, // tree-sitter node.is_named
13
+ "text": "<text>", // only for leaf nodes
14
+ "start_line": 0, // 0-based
15
+ "start_col": 0,
16
+ "end_line": 0,
17
+ "end_col": 0,
18
+ "children": [ ... ] // recursive; omitted for leaves
19
+ }
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import json
25
+ import logging
26
+ from typing import TYPE_CHECKING, Any
27
+
28
+ logger = logging.getLogger(__name__)
29
+
30
+ if TYPE_CHECKING:
31
+ # tree_sitter.Node is only imported at runtime inside functions so that
32
+ # this module can be imported without tree-sitter being installed in tests
33
+ # that mock out the CST serializer.
34
+ from tree_sitter import Node
35
+
36
+ _MAX_TEXT_BYTES = 4096 # truncate leaf text beyond this to avoid huge payloads
37
+
38
+
39
+ def _node_to_dict(node: "Node", source_bytes: bytes) -> dict[str, Any]:
40
+ """Recursively convert a tree-sitter Node to a plain dict.
41
+
42
+ Only *named* nodes are included — anonymous punctuation tokens (``:``,
43
+ ``(``, ``)``, keyword literals, etc.) are omitted. This keeps payloads
44
+ small: a typical Python file drops from ~3 000 nodes to ~2 000 nodes and
45
+ reduces the JSON size by 30-50 %. No semantic parser in the plugin
46
+ ecosystem uses unnamed nodes; the generic parser already discards unnamed
47
+ leaf nodes on its own side.
48
+ """
49
+ start = node.start_point # (row, col) — 0-based
50
+ end = node.end_point
51
+
52
+ obj: dict[str, Any] = {
53
+ "type": node.type,
54
+ "named": node.is_named,
55
+ "start_line": start[0],
56
+ "start_col": start[1],
57
+ "end_line": end[0],
58
+ "end_col": end[1],
59
+ }
60
+
61
+ named_children = node.named_children # list[Node] — unnamed nodes excluded
62
+ if named_children:
63
+ obj["children"] = [_node_to_dict(child, source_bytes) for child in named_children]
64
+ else:
65
+ # Leaf, or a node whose only children are unnamed punctuation.
66
+ # Include the raw source text so plugins can read identifiers / literals.
67
+ raw = source_bytes[node.start_byte : node.end_byte]
68
+ if len(raw) > _MAX_TEXT_BYTES:
69
+ logger.debug(
70
+ "Leaf text truncated: %d bytes → %d for node type %r",
71
+ len(raw), _MAX_TEXT_BYTES, node.type,
72
+ )
73
+ text = raw[:_MAX_TEXT_BYTES].decode("utf-8", errors="replace")
74
+ obj["text"] = text
75
+
76
+ return obj
77
+
78
+
79
+ def serialize_cst(root: "Node", source_bytes: bytes) -> str:
80
+ """
81
+ Serialize a tree-sitter parse tree to a compact JSON string.
82
+
83
+ Parameters
84
+ ----------
85
+ root:
86
+ The root ``Node`` returned by ``tree_sitter.Parser.parse()``.
87
+ source_bytes:
88
+ The exact ``bytes`` object that was passed to the parser.
89
+
90
+ Returns
91
+ -------
92
+ str
93
+ A UTF-8 JSON string. Separators are compact (no extra spaces).
94
+ """
95
+ d = _node_to_dict(root, source_bytes)
96
+ return json.dumps(d, separators=(",", ":"), ensure_ascii=False)
97
+
98
+
99
+ def deserialize_cst(cst_json: str) -> dict[str, Any]:
100
+ """Parse a CST JSON string back into a plain dict (for tests / inspection)."""
101
+ return json.loads(cst_json) # type: ignore[no-any-return]
@@ -0,0 +1,87 @@
1
+ """
2
+ intentumdiff.core.diffignore
3
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4
+
5
+ ``.diffignore`` file loading and path filtering.
6
+
7
+ A ``.diffignore`` file placed in the repository root follows the same
8
+ **gitwildmatch** syntax as ``.gitignore``:
9
+
10
+ * Blank lines and lines beginning with ``#`` are ignored.
11
+ * A leading ``/`` anchors the pattern to the root.
12
+ * A trailing ``/`` means "match this directory (and everything under it)".
13
+ * ``*`` matches any character sequence that does not contain ``/``.
14
+ * ``**`` matches across path components.
15
+ * A leading ``!`` negates a previous pattern.
16
+
17
+ Examples::
18
+
19
+ # Ignore generated files
20
+ target/
21
+ dist/
22
+ *.lock
23
+ **/generated/**
24
+ !important.lock # keep this specific lock file
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import logging
30
+ from pathlib import Path
31
+ from typing import TYPE_CHECKING
32
+
33
+ logger = logging.getLogger(__name__)
34
+
35
+ if TYPE_CHECKING:
36
+ import pathspec
37
+
38
+ #: Conventional filename — place in the repo / directory root.
39
+ DIFFIGNORE_FILENAME = ".diffignore"
40
+
41
+
42
+ def load_diffignore(root: str | Path) -> "DiffIgnore | None":
43
+ """
44
+ Look for a ``.diffignore`` file in *root* and return a :class:`DiffIgnore`
45
+ instance if found, or ``None`` when the file does not exist.
46
+
47
+ A warning is logged (but not raised) if the file exists but cannot be read.
48
+ """
49
+ path = Path(root) / DIFFIGNORE_FILENAME
50
+ if not path.is_file():
51
+ return None
52
+
53
+ try:
54
+ text = path.read_text(encoding="utf-8")
55
+ except OSError as exc:
56
+ logger.warning("Could not read %s: %s", path, exc)
57
+ return None
58
+
59
+ import pathspec # lazy — keep import-time fast when diffignore is absent
60
+
61
+ spec = pathspec.PathSpec.from_lines("gitignore", text.splitlines())
62
+ logger.debug("Loaded .diffignore from %s (%d pattern(s))", path, len(spec.patterns))
63
+ return DiffIgnore(spec)
64
+
65
+
66
+ class DiffIgnore:
67
+ """
68
+ Wraps a ``pathspec.PathSpec`` to test whether relative file paths should
69
+ be excluded from the diff / index pipeline.
70
+
71
+ Instances are created by :func:`load_diffignore`; construct one directly
72
+ only in tests.
73
+ """
74
+
75
+ __slots__ = ("_spec",)
76
+
77
+ def __init__(self, spec: "pathspec.PathSpec") -> None:
78
+ self._spec = spec
79
+
80
+ def is_ignored(self, rel_path: str) -> bool:
81
+ """
82
+ Return ``True`` if *rel_path* is matched by any pattern in the file.
83
+
84
+ *rel_path* must use **forward slashes** (POSIX style), e.g.
85
+ ``"src/generated/foo.py"`` — not ``"src\\generated\\foo.py"``.
86
+ """
87
+ return bool(self._spec.match_file(rel_path))
@@ -0,0 +1,189 @@
1
+ """
2
+ intentumdiff.core.index
3
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
4
+
5
+ ``SemanticIndex`` — a per-commit, multi-file symbol table.
6
+
7
+ Each ``SemanticIndex`` holds the ``SemanticNode`` trees for every file in a
8
+ repository snapshot (or any other collection of files). It provides:
9
+
10
+ * ``add_tree(filename, language, tree)`` — register one file's parsed tree.
11
+ * ``build()`` — extract the flat symbol table and reference table.
12
+ * ``find_definition(name)`` — look up a symbol by qualified name.
13
+ * ``find_references(name, resolve=False)`` — return call-site / import usages.
14
+ Pass ``resolve=True`` to attach the matching ``SymbolDefinition`` when
15
+ exactly one definition is found.
16
+
17
+ The heavy lifting (symbol-table + reference-table extraction) is delegated to
18
+ the Rust core (``index-engine-lib``, via the native ``build_symbol_table_json``
19
+ / ``build_reference_table_json`` entrypoints). Rust is authoritative — the
20
+ former pure-Python extraction mirror was deleted (#91); without the core the
21
+ tables are simply empty ("if Python didn't exist, the engine still lives in
22
+ Rust"). Cross-file diffing lives in ``intentumdiff.analysis.cross_file``, also a
23
+ thin wrapper over the same Rust core.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ import json
29
+ from typing import TYPE_CHECKING
30
+
31
+ from intentumdiff.core.models import ReferenceUsage, SymbolDefinition
32
+
33
+ if TYPE_CHECKING:
34
+ from intentumdiff.core.models import SemanticNode
35
+
36
+ class SemanticIndex:
37
+ """
38
+ Multi-file symbol table for a single repository snapshot.
39
+
40
+ Usage::
41
+
42
+ differ = SemanticDiffer(config)
43
+ old_index = SemanticIndex()
44
+ for filename, source in old_files.items():
45
+ diff = differ._parse(source, filename) # internal helper
46
+ old_index.add_tree(filename, diff.language, diff.tree)
47
+ old_index.build()
48
+
49
+ # Then compare two snapshots with
50
+ # intentumdiff.analysis.cross_file.detect_cross_file_changes(old, new).
51
+ """
52
+
53
+ def __init__(self) -> None:
54
+ # Raw input: list of (filename, language, tree) triples
55
+ self._files: list[tuple[str, str, "SemanticNode"]] = []
56
+ # Symbol table built by build()
57
+ self._symbols: dict[str, list[SymbolDefinition]] = {}
58
+ # Reference table built by build()
59
+ self._references: dict[str, list[ReferenceUsage]] = {}
60
+ self._built: bool = False
61
+
62
+ # ------------------------------------------------------------------
63
+ # Mutation API
64
+ # ------------------------------------------------------------------
65
+
66
+ def add_tree(self, filename: str, language: str, tree: "SemanticNode") -> None:
67
+ """Register a parsed semantic tree for *filename*."""
68
+ if self._built:
69
+ raise RuntimeError(
70
+ "SemanticIndex is already built; create a new instance to add more trees."
71
+ )
72
+ self._files.append((filename, language, tree))
73
+
74
+ # ------------------------------------------------------------------
75
+ # Build
76
+ # ------------------------------------------------------------------
77
+
78
+ def build(self) -> "SemanticIndex":
79
+ """Build the symbol + reference tables via the Rust core (index-engine-lib).
80
+
81
+ Rust-authoritative (#91): extraction runs in the native
82
+ ``build_symbol_table_json`` / ``build_reference_table_json`` entrypoints
83
+ (the same code the index-engine Wasm plugin wraps). The former Python
84
+ extraction mirror was deleted. When the core is unavailable the tables
85
+ stay empty rather than falling back — "if Python didn't exist, the
86
+ engine still lives in Rust".
87
+ """
88
+ from intentumdiff.rust_core import (
89
+ try_rust_build_reference_table,
90
+ try_rust_build_symbol_table,
91
+ )
92
+
93
+ self._symbols = {}
94
+ self._references = {}
95
+ files_json = self.to_files_json()
96
+ symbol_json = try_rust_build_symbol_table(files_json)
97
+ if symbol_json is not None:
98
+ self.load_symbol_table_json(symbol_json)
99
+ reference_json = try_rust_build_reference_table(files_json)
100
+ if reference_json is not None:
101
+ self.load_reference_table_json(reference_json)
102
+ self._built = True
103
+ return self
104
+
105
+ # ------------------------------------------------------------------
106
+ # Query API
107
+ # ------------------------------------------------------------------
108
+
109
+ @property
110
+ def symbols(self) -> dict[str, list[SymbolDefinition]]:
111
+ """Return the flat symbol table (qualified-name → definitions)."""
112
+ if not self._built:
113
+ raise RuntimeError("Call build() first.")
114
+ return self._symbols
115
+
116
+ @property
117
+ def references(self) -> dict[str, list[ReferenceUsage]]:
118
+ """Return the reference table (label → usage sites)."""
119
+ if not self._built:
120
+ raise RuntimeError("Call build() first.")
121
+ return self._references
122
+
123
+ def find_definition(self, name: str) -> list[SymbolDefinition]:
124
+ """Return all definitions matching *name* (exact qualified-name lookup)."""
125
+ if not self._built:
126
+ raise RuntimeError("Call build() first.")
127
+ return self._symbols.get(name, [])
128
+
129
+ def find_references(self, name: str, resolve: bool = False) -> list[ReferenceUsage]:
130
+ """
131
+ Return call-site / import usages of *name*.
132
+
133
+ Parameters
134
+ ----------
135
+ name:
136
+ The label to search for (e.g. ``"do_work"`` or ``"MyClass"``).
137
+ resolve:
138
+ When ``True``, populate ``ReferenceUsage.resolved_definition`` for
139
+ each result if exactly one matching ``SymbolDefinition`` is found
140
+ in this index. Defaults to ``False`` (raw usages only).
141
+ """
142
+ if not self._built:
143
+ raise RuntimeError("Call build() first.")
144
+ refs = self._references.get(name, [])
145
+ if not resolve:
146
+ return refs
147
+ # Attach resolved definition when the match is unambiguous.
148
+ defs = self.find_definition(name)
149
+ resolved = defs[0] if len(defs) == 1 else None
150
+ return [
151
+ ref.model_copy(update={"resolved_definition": resolved}) for ref in refs
152
+ ]
153
+
154
+ # ------------------------------------------------------------------
155
+ # Serialisation helpers (feed the native index-engine primitives)
156
+ # ------------------------------------------------------------------
157
+
158
+ def to_files_json(self) -> str:
159
+ """Serialise the registered trees to the JSON format expected by the
160
+ Rust core's ``build_symbol_table_json`` / ``build_reference_table_json``
161
+ entrypoints (a JSON array of ``{filename, language, tree}`` entries)."""
162
+ payload = [
163
+ {"filename": filename, "language": language, "tree": json.loads(tree.model_dump_json())}
164
+ for filename, language, tree in self._files
165
+ ]
166
+ return json.dumps(payload)
167
+
168
+ def load_symbol_table_json(self, json_str: str) -> None:
169
+ """
170
+ Populate ``_symbols`` from a SymbolTable JSON returned by the Rust core's
171
+ ``build_symbol_table_json`` entrypoint.
172
+ """
173
+ raw: dict[str, list[dict]] = json.loads(json_str)
174
+ self._symbols = {
175
+ qname: [SymbolDefinition(**entry) for entry in entries]
176
+ for qname, entries in raw.items()
177
+ }
178
+ self._built = True
179
+
180
+ def load_reference_table_json(self, json_str: str) -> None:
181
+ """
182
+ Populate ``_references`` from a ReferenceTable JSON returned by the Rust
183
+ core's ``build_reference_table_json`` entrypoint.
184
+ """
185
+ raw: dict[str, list[dict]] = json.loads(json_str)
186
+ self._references = {
187
+ label: [ReferenceUsage(**entry) for entry in entries]
188
+ for label, entries in raw.items()
189
+ }