intentumdiff-python 0.0.1__py3-none-macosx_11_0_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/libintentumdiff_rust_core.dylib +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,46 @@
1
+ """
2
+ intentumdiff.analysis.text_review
3
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4
+
5
+ The generic-text review WRAPPER. Parser token churn is replaced with stable
6
+ line/character spans by the Rust core (``try_rust_generic_text_review`` →
7
+ ``text_review_generic.rs``), which is AUTHORITATIVE (readiness #90/#91) — there
8
+ is no Python engine fallback. Only the ``PresentationResult`` DTO and the thin
9
+ Rust wrapper survive here; the former Python mirror implementation was deleted
10
+ once the Rust generic-text review became the only engine.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from dataclasses import dataclass, field
16
+ from typing import Any
17
+
18
+ from intentumdiff.core.models import Change, ChangeGroup
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class PresentationResult:
23
+ changes: list[Change]
24
+ change_groups: list[ChangeGroup] = field(default_factory=list)
25
+ ignored_style_changes: list[dict[str, Any]] = field(default_factory=list)
26
+
27
+
28
+ def normalize_generic_text_for_review(
29
+ changes: list[Change],
30
+ old_source: str,
31
+ new_source: str,
32
+ ) -> PresentationResult:
33
+ """Replace generic parser token churn with line/character text spans.
34
+
35
+ Rust-authoritative (readiness #90/#91): the Rust generic-text review is the
36
+ only implementation. When it declines (backend unavailable, or the input
37
+ exceeds its size cap), the changes pass through unchanged — "if Python didn't
38
+ exist, IntentumDiff still works". The full port lives in ``text_review_generic.rs``.
39
+ """
40
+ from intentumdiff.rust_core import try_rust_generic_text_review
41
+
42
+ rust_review = try_rust_generic_text_review(old_source, new_source, len(changes))
43
+ if rust_review is not None:
44
+ rust_changes, rust_groups = rust_review
45
+ return PresentationResult(changes=rust_changes, change_groups=rust_groups)
46
+ return PresentationResult(changes=changes)
@@ -0,0 +1,430 @@
1
+ """
2
+ User-registerable schema/diff profiles (issue #63, external-config path).
3
+
4
+ Teams can teach the engine their own JSON/YAML dialects without a code change by
5
+ dropping declarative descriptor files into a schemas directory:
6
+
7
+ - ``~/.intentumdiff/schemas/*.yml`` (or ``INTENTUMDIFF_USER_SCHEMA_DIR``)
8
+ - ``<cwd>/.intentumdiff/schemas/*.yml`` (project-level, wins over the home dir)
9
+
10
+ A descriptor registers one of three modes (all offline-first):
11
+
12
+ 1. **Profile descriptor** — identity/keying written directly::
13
+
14
+ language_id: acme-service-config
15
+ match:
16
+ filename_patterns: ["service.acme.json"]
17
+ root_markers: ["acmeApiVersion"]
18
+ identity_fields: [name]
19
+ keyed_arrays: { /routes: [path, method] }
20
+
21
+ 2. **Local JSON Schema file** — ``schema: ./service.schema.json`` (relative to
22
+ the descriptor). Identity hints are derived with the same extraction the
23
+ resolver applies to remote provider schemas. The file is read locally and is
24
+ **never fetched or logged** — the privacy-preferred path for proprietary
25
+ schemas.
26
+
27
+ 3. **Provider entry** — ``match.schema_urls`` claims a document's declared
28
+ ``$schema`` URL so internal dialects resolve **offline** instead of via the
29
+ guarded fetch path.
30
+
31
+ The registry is thin shell + config: descriptors are validated here and their
32
+ identity fields are marshaled through the existing ``SchemaResolution`` channel
33
+ into the Rust core's keyed matching. Malformed descriptors fail closed — the
34
+ whole file is rejected with a clear error and built-in resolution proceeds.
35
+ """
36
+
37
+ from __future__ import annotations
38
+
39
+ import fnmatch
40
+ import hashlib
41
+ import json
42
+ import logging
43
+ import os
44
+ import re
45
+ from collections.abc import Mapping
46
+ from dataclasses import dataclass, field
47
+ from pathlib import Path
48
+ from typing import Any
49
+
50
+ import yaml
51
+
52
+ logger = logging.getLogger(__name__)
53
+
54
+ USER_SCHEMA_DIR_ENV = "INTENTUMDIFF_USER_SCHEMA_DIR"
55
+ USER_SCHEMAS_TOGGLE_ENV = "INTENTUMDIFF_USER_SCHEMAS"
56
+
57
+ # Provider-id roots owned by built-in detection; a registered language_id must
58
+ # not collide with these (the invariance guard from issue #63's acceptance).
59
+ BUILTIN_PROVIDER_ROOTS = frozenset(
60
+ {
61
+ "adf",
62
+ "azure-pipelines",
63
+ "databricks",
64
+ "dbt",
65
+ "embedded",
66
+ "github-actions",
67
+ "kubernetes",
68
+ "none",
69
+ "openapi",
70
+ "user",
71
+ }
72
+ )
73
+
74
+ _DESCRIPTOR_SUFFIXES = (".yml", ".yaml", ".json")
75
+
76
+
77
+ @dataclass(frozen=True)
78
+ class UserSchemaProfile:
79
+ language_id: str
80
+ source_path: str
81
+ filename_patterns: tuple[str, ...] = ()
82
+ root_markers: tuple[str, ...] = ()
83
+ schema_urls: tuple[str, ...] = ()
84
+ identity_fields: frozenset[str] = frozenset()
85
+ important_paths: tuple[str, ...] = ()
86
+ scaffold_paths: tuple[str, ...] = ()
87
+ schema: dict[str, Any] | None = None
88
+ schema_path: str | None = None
89
+ # XML dialect fields (issue #86): element tag -> key fields (child-element
90
+ # text, or attr:NAME attribute values), plus the Rust-side match predicate.
91
+ keyed_elements: dict[str, tuple[str, ...]] = field(default_factory=dict)
92
+ namespace: str | None = None
93
+ root_element: str | None = None
94
+ fingerprint: str = ""
95
+
96
+ @property
97
+ def provider_id(self) -> str:
98
+ return f"user:{self.language_id}"
99
+
100
+
101
+ def user_schema_dirs(env: Mapping[str, str] | None = None) -> tuple[Path, ...]:
102
+ """Descriptor directories in precedence order (first match wins)."""
103
+ values = env or os.environ
104
+ dirs: list[Path] = [Path.cwd() / ".intentumdiff" / "schemas"]
105
+ override = values.get(USER_SCHEMA_DIR_ENV)
106
+ if override:
107
+ dirs.append(Path(override))
108
+ else:
109
+ dirs.append(Path.home() / ".intentumdiff" / "schemas")
110
+ return tuple(dirs)
111
+
112
+
113
+ def user_schemas_enabled(env: Mapping[str, str] | None = None) -> bool:
114
+ values = env or os.environ
115
+ return (values.get(USER_SCHEMAS_TOGGLE_ENV) or "").strip().lower() not in {
116
+ "off",
117
+ "0",
118
+ "false",
119
+ }
120
+
121
+
122
+ # Cache keyed by a stat snapshot of every descriptor file, so edits (and test
123
+ # tmp dirs) invalidate naturally without a process restart.
124
+ _CACHE: dict[tuple[Any, ...], tuple[tuple[UserSchemaProfile, ...], tuple[str, ...]]] = {}
125
+
126
+
127
+ def load_user_schema_profiles(
128
+ env: Mapping[str, str] | None = None,
129
+ ) -> tuple[tuple[UserSchemaProfile, ...], tuple[str, ...]]:
130
+ """Load, validate, and cache every registered descriptor.
131
+
132
+ Returns ``(profiles, errors)``. A descriptor file that fails validation
133
+ contributes an error message and NO profiles (fail closed, never partially
134
+ applied).
135
+ """
136
+ if not user_schemas_enabled(env):
137
+ return ((), ())
138
+ files: list[Path] = []
139
+ for directory in user_schema_dirs(env):
140
+ if not directory.is_dir():
141
+ continue
142
+ for entry in sorted(directory.iterdir()):
143
+ if entry.suffix.lower() in _DESCRIPTOR_SUFFIXES and entry.is_file():
144
+ files.append(entry)
145
+ key = tuple(
146
+ (str(path), stat.st_mtime_ns, stat.st_size)
147
+ for path in files
148
+ for stat in (path.stat(),)
149
+ )
150
+ cached = _CACHE.get(key)
151
+ if cached is not None:
152
+ return cached
153
+
154
+ profiles: list[UserSchemaProfile] = []
155
+ errors: list[str] = []
156
+ seen_ids: dict[str, str] = {}
157
+ for path in files:
158
+ loaded, file_errors = _load_descriptor_file(path)
159
+ if file_errors:
160
+ errors.extend(file_errors)
161
+ continue
162
+ for profile in loaded:
163
+ if profile.language_id in seen_ids:
164
+ # First registration wins (project dir precedes home dir).
165
+ if seen_ids[profile.language_id] != str(path):
166
+ logger.warning(
167
+ "user schema %r in %s shadowed by earlier registration in %s",
168
+ profile.language_id,
169
+ path,
170
+ seen_ids[profile.language_id],
171
+ )
172
+ continue
173
+ seen_ids[profile.language_id] = str(path)
174
+ profiles.append(profile)
175
+ for message in errors:
176
+ logger.warning("user schema descriptor rejected: %s", message)
177
+ result = (tuple(profiles), tuple(errors))
178
+ _CACHE[key] = result
179
+ return result
180
+
181
+
182
+ def match_user_profile(
183
+ profiles: tuple[UserSchemaProfile, ...],
184
+ *,
185
+ filename: str,
186
+ content: str,
187
+ declared_url: str | None = None,
188
+ ) -> UserSchemaProfile | None:
189
+ """First profile claiming the document, by declared ``$schema`` URL first
190
+ (mode 3), then filename patterns / root markers (modes 1 and 2)."""
191
+ if declared_url:
192
+ for profile in profiles:
193
+ if declared_url in profile.schema_urls:
194
+ return profile
195
+ normalized_path = filename.replace("\\", "/").lower()
196
+ basename = normalized_path.rsplit("/", 1)[-1]
197
+ for profile in profiles:
198
+ if profile.filename_patterns:
199
+ if not any(
200
+ fnmatch.fnmatch(basename, pattern) or fnmatch.fnmatch(normalized_path, pattern)
201
+ for pattern in profile.filename_patterns
202
+ ):
203
+ continue
204
+ if _root_markers_match(profile.root_markers, content):
205
+ return profile
206
+ elif profile.root_markers and _root_markers_match(profile.root_markers, content):
207
+ return profile
208
+ return None
209
+
210
+
211
+ def _root_markers_match(markers: tuple[str, ...], content: str) -> bool:
212
+ """Heuristic top-level-key check, consistent with the built-in provider
213
+ detectors (regex over raw text — no full parse on the hot path)."""
214
+ if not markers:
215
+ return True
216
+ return all(
217
+ re.search(rf'^\s*"?{re.escape(marker)}"?\s*:', content, re.MULTILINE)
218
+ for marker in markers
219
+ )
220
+
221
+
222
+ def _load_descriptor_file(
223
+ path: Path,
224
+ ) -> tuple[tuple[UserSchemaProfile, ...], tuple[str, ...]]:
225
+ try:
226
+ raw_text = path.read_text(encoding="utf-8")
227
+ documents = [doc for doc in yaml.safe_load_all(raw_text) if doc is not None]
228
+ except Exception as exc: # noqa: BLE001 - any parse failure fails the file closed
229
+ return ((), (f"{path}: unreadable descriptor ({exc})",))
230
+ profiles: list[UserSchemaProfile] = []
231
+ errors: list[str] = []
232
+ for index, document in enumerate(documents):
233
+ profile, document_errors = _validate_descriptor(document, path, index, raw_text)
234
+ if document_errors:
235
+ errors.extend(document_errors)
236
+ elif profile is not None:
237
+ profiles.append(profile)
238
+ if errors:
239
+ # Fail the whole file closed — never partially apply a descriptor file.
240
+ return ((), tuple(errors))
241
+ if not profiles:
242
+ return ((), (f"{path}: descriptor file contains no profiles",))
243
+ return (tuple(profiles), ())
244
+
245
+
246
+ def _validate_descriptor(
247
+ document: Any,
248
+ path: Path,
249
+ index: int,
250
+ raw_text: str,
251
+ ) -> tuple[UserSchemaProfile | None, tuple[str, ...]]:
252
+ where = f"{path}#{index}"
253
+ if not isinstance(document, dict):
254
+ return (None, (f"{where}: descriptor must be a mapping",))
255
+ errors: list[str] = []
256
+
257
+ language_id = document.get("language_id")
258
+ if not isinstance(language_id, str) or not language_id.strip():
259
+ errors.append(f"{where}: 'language_id' is required and must be a string")
260
+ language_id = ""
261
+ else:
262
+ language_id = language_id.strip()
263
+ root = language_id.split(":", 1)[0].lower()
264
+ if root in BUILTIN_PROVIDER_ROOTS:
265
+ errors.append(
266
+ f"{where}: language_id {language_id!r} collides with the "
267
+ f"built-in provider root {root!r}"
268
+ )
269
+
270
+ match = document.get("match") or {}
271
+ if not isinstance(match, dict):
272
+ errors.append(f"{where}: 'match' must be a mapping")
273
+ match = {}
274
+ filename_patterns = _string_tuple(
275
+ match.get("filename_patterns"), f"{where}: match.filename_patterns", errors
276
+ )
277
+ root_markers = _string_tuple(match.get("root_markers"), f"{where}: match.root_markers", errors)
278
+ schema_urls = _string_tuple(match.get("schema_urls"), f"{where}: match.schema_urls", errors)
279
+ namespace = match.get("namespace")
280
+ if namespace is not None and (not isinstance(namespace, str) or not namespace.strip()):
281
+ errors.append(f"{where}: match.namespace must be a non-empty string")
282
+ namespace = None
283
+ root_element = match.get("root_element")
284
+ if root_element is not None and (not isinstance(root_element, str) or not root_element.strip()):
285
+ errors.append(f"{where}: match.root_element must be a non-empty string")
286
+ root_element = None
287
+ has_match = (
288
+ filename_patterns or root_markers or schema_urls or namespace or root_element
289
+ )
290
+ if not has_match:
291
+ errors.append(f"{where}: 'match' needs filename_patterns, root_markers, or schema_urls")
292
+
293
+ identity: set[str] = set(
294
+ _string_tuple(document.get("identity_fields"), f"{where}: identity_fields", errors)
295
+ )
296
+ keyed_arrays = document.get("keyed_arrays") or {}
297
+ if not isinstance(keyed_arrays, dict):
298
+ errors.append(f"{where}: 'keyed_arrays' must be a mapping of path -> identity fields")
299
+ keyed_arrays = {}
300
+ for array_path, key_fields in keyed_arrays.items():
301
+ fields = key_fields if isinstance(key_fields, list) else [key_fields]
302
+ for key_field in fields:
303
+ if not isinstance(key_field, str) or not key_field.strip():
304
+ errors.append(f"{where}: keyed_arrays[{array_path!r}] entries must be strings")
305
+ else:
306
+ identity.add(key_field.strip())
307
+
308
+ keyed_elements: dict[str, tuple[str, ...]] = {}
309
+ raw_keyed_elements = document.get("keyed_elements") or {}
310
+ if not isinstance(raw_keyed_elements, dict):
311
+ errors.append(f"{where}: 'keyed_elements' must be a mapping of element tag -> key fields")
312
+ raw_keyed_elements = {}
313
+ for tag, key_fields in raw_keyed_elements.items():
314
+ fields = key_fields if isinstance(key_fields, list) else [key_fields]
315
+ clean: list[str] = []
316
+ for key_field in fields:
317
+ if not isinstance(key_field, str) or not key_field.strip():
318
+ errors.append(f"{where}: keyed_elements[{tag!r}] entries must be strings")
319
+ else:
320
+ clean.append(key_field.strip())
321
+ if not isinstance(tag, str) or not tag.strip():
322
+ errors.append(f"{where}: keyed_elements tags must be strings")
323
+ elif clean:
324
+ keyed_elements[tag.strip()] = tuple(clean)
325
+ if keyed_elements and not namespace and not root_element:
326
+ # The engine-side dialect predicate matches by namespace/root element -
327
+ # filename alone cannot reach the Rust matcher. Fail closed.
328
+ errors.append(
329
+ f"{where}: an XML dialect (keyed_elements) needs match.namespace "
330
+ "or match.root_element"
331
+ )
332
+
333
+ important_paths = _string_tuple(
334
+ document.get("important_paths"), f"{where}: important_paths", errors
335
+ )
336
+ scaffold_paths = _string_tuple(
337
+ document.get("scaffold_paths"), f"{where}: scaffold_paths", errors
338
+ )
339
+
340
+ schema_dict: dict[str, Any] | None = None
341
+ schema_path: str | None = None
342
+ schema_ref = document.get("schema")
343
+ if schema_ref is not None:
344
+ if not isinstance(schema_ref, str) or not schema_ref.strip():
345
+ errors.append(f"{where}: 'schema' must be a local file path")
346
+ else:
347
+ resolved = (path.parent / schema_ref).resolve()
348
+ try:
349
+ loaded = json.loads(resolved.read_text(encoding="utf-8"))
350
+ except FileNotFoundError:
351
+ errors.append(f"{where}: schema file not found: {resolved}")
352
+ loaded = None
353
+ except Exception as exc: # noqa: BLE001
354
+ errors.append(f"{where}: schema file unreadable ({exc})")
355
+ loaded = None
356
+ if loaded is not None:
357
+ if not isinstance(loaded, dict):
358
+ errors.append(f"{where}: schema file must contain a JSON object")
359
+ else:
360
+ schema_dict = loaded
361
+ schema_path = str(resolved)
362
+ # Same conservative hint extraction the resolver applies to
363
+ # remote provider schemas — local, no fetch.
364
+ from intentumdiff.analysis.schema_resolver import derive_identity_fields
365
+
366
+ identity |= derive_identity_fields(loaded)
367
+
368
+ if not identity and not keyed_elements:
369
+ errors.append(
370
+ f"{where}: no identity source — provide identity_fields, keyed_arrays, "
371
+ "or a local schema that yields identity hints"
372
+ )
373
+ if errors:
374
+ return (None, tuple(errors))
375
+
376
+ digest = hashlib.sha256()
377
+ digest.update(raw_text.encode("utf-8"))
378
+ if schema_path:
379
+ digest.update(Path(schema_path).read_bytes())
380
+ return (
381
+ UserSchemaProfile(
382
+ language_id=language_id,
383
+ source_path=str(path),
384
+ filename_patterns=filename_patterns,
385
+ root_markers=root_markers,
386
+ schema_urls=schema_urls,
387
+ identity_fields=frozenset(identity),
388
+ important_paths=important_paths,
389
+ scaffold_paths=scaffold_paths,
390
+ schema=schema_dict,
391
+ schema_path=schema_path,
392
+ keyed_elements=keyed_elements,
393
+ namespace=namespace.strip() if isinstance(namespace, str) else None,
394
+ root_element=root_element.strip() if isinstance(root_element, str) else None,
395
+ fingerprint=f"user:{language_id}:{digest.hexdigest()[:16]}",
396
+ ),
397
+ (),
398
+ )
399
+
400
+
401
+ def _string_tuple(value: Any, where: str, errors: list[str]) -> tuple[str, ...]:
402
+ if value is None:
403
+ return ()
404
+ if not isinstance(value, list):
405
+ errors.append(f"{where} must be a list of strings")
406
+ return ()
407
+ result: list[str] = []
408
+ for item in value:
409
+ if not isinstance(item, str) or not item.strip():
410
+ errors.append(f"{where} entries must be non-empty strings")
411
+ else:
412
+ result.append(item.strip())
413
+ return tuple(result)
414
+
415
+
416
+ def user_xml_dialects_payload(
417
+ profiles: tuple[UserSchemaProfile, ...],
418
+ ) -> list[dict[str, Any]]:
419
+ """The engine-side dialect specs (issue #86) for profiles that declare
420
+ ``keyed_elements`` — marshaled as-is into the Rust registry."""
421
+ return [
422
+ {
423
+ "language_id": profile.language_id,
424
+ "root_element": profile.root_element,
425
+ "namespace": profile.namespace,
426
+ "keyed_elements": {tag: list(fields) for tag, fields in profile.keyed_elements.items()},
427
+ }
428
+ for profile in profiles
429
+ if profile.keyed_elements
430
+ ]
intentumdiff/assets.py ADDED
@@ -0,0 +1,45 @@
1
+ """Thin Python bridge for Rust-owned perceptual asset diffs."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ from intentumdiff.rust_core import _load_backend
10
+
11
+
12
+ def diff_image_assets(
13
+ *,
14
+ before_path: str | Path,
15
+ after_path: str | Path,
16
+ out_dir: str | Path,
17
+ options: dict[str, Any] | None = None,
18
+ ) -> dict[str, Any]:
19
+ backend = _load_backend()
20
+ raw = backend.diff_asset_image_json(
21
+ str(Path(before_path)),
22
+ str(Path(after_path)),
23
+ str(Path(out_dir)),
24
+ json.dumps(options or {}, separators=(",", ":")),
25
+ )
26
+ return json.loads(raw)
27
+
28
+
29
+ def diff_git_assets(
30
+ *,
31
+ repo_path: str | Path,
32
+ base: str,
33
+ head: str,
34
+ out_dir: str | Path,
35
+ options: dict[str, Any] | None = None,
36
+ ) -> dict[str, Any]:
37
+ backend = _load_backend()
38
+ raw = backend.diff_git_assets_json(
39
+ str(Path(repo_path)),
40
+ base,
41
+ head,
42
+ str(Path(out_dir)),
43
+ json.dumps(options or {}, separators=(",", ":")),
44
+ )
45
+ return json.loads(raw)
@@ -0,0 +1,37 @@
1
+ """
2
+ intentumdiff.cache
3
+ ~~~~~~~~~~~~~~~~~~~~~~
4
+
5
+ Disk-persistent caching and analytics for the semantic diff pipeline.
6
+
7
+ Two stores are provided:
8
+
9
+ ``SqliteCacheStore``
10
+ Stores parse-tree and diff results keyed by content + grammar hash.
11
+ Backed by SQLite with WAL mode; safe for concurrent readers.
12
+ Evicts entries by TTL and total DB size.
13
+
14
+ ``DuckDBAnalyticsStore``
15
+ Append-only diff-history store backed by DuckDB.
16
+ Exposes a ``query(sql)`` method for ad-hoc analytics.
17
+
18
+ Typical usage::
19
+
20
+ from intentumdiff import SemanticDiffer
21
+ from intentumdiff.core.models import DiffConfig
22
+ from pathlib import Path
23
+
24
+ config = DiffConfig(
25
+ cache_path=Path(".intentumdiff-cache"),
26
+ cache_ttl_days=30,
27
+ cache_max_mb=500,
28
+ analytics_path=Path(".intentumdiff-cache"),
29
+ )
30
+ differ = SemanticDiffer(config=config)
31
+ """
32
+
33
+ from intentumdiff.cache.store import CacheStore
34
+ from intentumdiff.cache.sqlite_store import SqliteCacheStore
35
+ from intentumdiff.cache.duckdb_store import DuckDBAnalyticsStore
36
+
37
+ __all__ = ["CacheStore", "SqliteCacheStore", "DuckDBAnalyticsStore"]
@@ -0,0 +1,98 @@
1
+ """
2
+ intentumdiff.cache.duckdb_store
3
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4
+
5
+ Append-only diff-history + fuel-diagnostics analytics store — a thin delegator over
6
+ the native Rust ``AnalyticsStore`` (#101, A2.2).
7
+
8
+ The schema, fuel-normalization, queries, and the read-only-query guard all live in the
9
+ shared Rust core (``crates/rust-core-host/src/analytics.rs``), so every binding records
10
+ and queries analytics identically. The storage engine is chosen at runtime by the core:
11
+ the **provided** DuckDB (dlopen of a configurable ``libduckdb``) when available, else the
12
+ bundled **SQLite** fallback — so analytics always works, DuckDB is never bundled, and the
13
+ core never fails to load without it.
14
+
15
+ Note: the on-disk file is engine-specific (a DuckDB file vs a SQLite file); switching
16
+ engines between runs can't read the other's prior data. Fine for append-only telemetry.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import json
22
+ from pathlib import Path
23
+
24
+ from intentumdiff.rust_core import analytics_store
25
+
26
+
27
+ def _check_limit(limit: int) -> None:
28
+ if not isinstance(limit, int) or limit < 1:
29
+ raise ValueError("limit must be a positive integer")
30
+
31
+
32
+ class DuckDBAnalyticsStore:
33
+ """Delegator over the native analytics store (class name kept for API compatibility)."""
34
+
35
+ def __init__(self, path: Path | str) -> None:
36
+ self._rust = analytics_store(str(path))
37
+
38
+ @property
39
+ def backend(self) -> str:
40
+ """The active storage engine: ``"duckdb"`` or ``"sqlite"``."""
41
+ return self._rust.backend
42
+
43
+ # ── Write ─────────────────────────────────────────────────────────────
44
+
45
+ def record_diff(self, diff_json: str) -> None:
46
+ self._rust.record_diff(diff_json)
47
+
48
+ def record_diagnostics_run(
49
+ self,
50
+ diffs: list[str | dict],
51
+ *,
52
+ command: str = "",
53
+ repo: str = "",
54
+ argv: list[str] | None = None,
55
+ run_id: str | None = None,
56
+ ) -> str:
57
+ diffs_json = [d if isinstance(d, str) else json.dumps(d) for d in diffs]
58
+ return self._rust.record_diagnostics_run(
59
+ diffs_json, command, repo, json.dumps(argv or []), run_id
60
+ )
61
+
62
+ # ── Read ──────────────────────────────────────────────────────────────
63
+
64
+ def query(self, sql: str) -> list[dict]:
65
+ return json.loads(self._rust.query(sql))
66
+
67
+ def query_readonly(self, sql: str) -> list[dict]:
68
+ return json.loads(self._rust.query_readonly(sql))
69
+
70
+ def most_changed_files(self, limit: int = 20) -> list[dict]:
71
+ _check_limit(limit)
72
+ return json.loads(self._rust.most_changed_files(limit))
73
+
74
+ def changes_by_language(self) -> list[dict]:
75
+ return json.loads(self._rust.changes_by_language())
76
+
77
+ def recent_diagnostic_runs(self, limit: int = 10) -> list[dict]:
78
+ _check_limit(limit)
79
+ return json.loads(self._rust.recent_diagnostic_runs(limit))
80
+
81
+ def fuel_by_language(self, limit: int = 20) -> list[dict]:
82
+ _check_limit(limit)
83
+ return json.loads(self._rust.fuel_by_language(limit))
84
+
85
+ def top_fuel_hotspots(self, limit: int = 20) -> list[dict]:
86
+ _check_limit(limit)
87
+ return json.loads(self._rust.top_fuel_hotspots(limit))
88
+
89
+ # ── Lifecycle ─────────────────────────────────────────────────────────
90
+
91
+ def close(self) -> None:
92
+ self._rust.close()
93
+
94
+ def __enter__(self) -> "DuckDBAnalyticsStore":
95
+ return self
96
+
97
+ def __exit__(self, *_: object) -> None:
98
+ self.close()