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,1252 @@
1
+ """
2
+ intentumdiff.plugins.loader
3
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4
+
5
+ Wasm Component Model loader.
6
+
7
+ Uses wasmtime.component.Component + wasmtime.component.Linker to load and
8
+ instantiate plugins built with wasm32-wasip2 (WebAssembly Component Model).
9
+
10
+ Security properties
11
+ ────────────────────
12
+ - ``WasiConfig()`` grants zero capabilities (no dirs, env, stdio, args).
13
+ - ``store.set_fuel(n)`` caps CPU; traps are caught and re-raised as typed
14
+ Python exceptions.
15
+ - All dynamic content from the plugin is treated as untrusted.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import hashlib
21
+ import importlib.metadata as _importlib_metadata
22
+ import json
23
+ import logging
24
+ import os
25
+ import ssl
26
+ import threading
27
+ import time as _time
28
+ import urllib.request
29
+ from pathlib import Path
30
+ from typing import Any
31
+
32
+ from wasmtime import Config, Engine, Store, WasiConfig, WasmtimeError
33
+ from wasmtime.component import Component, Linker
34
+
35
+ from intentumdiff.plugins.exceptions import (
36
+ PluginFuelExhausted,
37
+ PluginLoadError,
38
+ PluginOutputError,
39
+ PluginSandboxViolation,
40
+ )
41
+
42
+ logger = logging.getLogger(__name__)
43
+ _MAX_TELEMETRY_RECORDS = 128
44
+
45
+ # ---------------------------------------------------------------------------
46
+ # Wasmtime vulnerability blocklist
47
+ # ---------------------------------------------------------------------------
48
+
49
+ # Exact PyPI versions of wasmtime that are known-vulnerable. Add new entries
50
+ # here when new CVEs are disclosed; each entry should carry a comment with the
51
+ # advisory ID so the reason is never ambiguous. The *runtime* gate uses this
52
+ # fast offline check. For a live OSV scan run: ``intentumdiff security-check``.
53
+ _VULNERABLE_WASMTIME_VERSIONS: frozenset[str] = frozenset({
54
+ "44.0.0", # CVE-2026-44216 / GHSA-p8xm-42r7-89xg — host panic via memory64
55
+ })
56
+ _WASMTIME_ADVISORY = "CVE-2026-44216 / GHSA-p8xm-42r7-89xg"
57
+ _WASMTIME_ADVISORY_URL = (
58
+ "https://github.com/bytecodealliance/wasmtime/security/advisories/"
59
+ "GHSA-p8xm-42r7-89xg"
60
+ )
61
+ _BUILTIN_WASM_DIR = (Path(__file__).parent.parent / "wasm").resolve()
62
+
63
+
64
+ def _is_trusted_wasm_path(wasm_path: str | Path | None) -> bool:
65
+ """Return true only for bundled first-party Wasm assets in this package."""
66
+ if wasm_path is None:
67
+ return False
68
+ try:
69
+ path = Path(wasm_path).resolve()
70
+ return path.is_relative_to(_BUILTIN_WASM_DIR)
71
+ except (OSError, RuntimeError, ValueError):
72
+ return False
73
+
74
+
75
+ #: The #89 provenance manifest shipped alongside the bundled parsers (filename -> SHA-256).
76
+ _PROVENANCE_MANIFEST = _BUILTIN_WASM_DIR / "wasm_provenance.json"
77
+ #: Opt-in to make a bundled-wasm provenance mismatch a hard load failure (release/CI). Off by
78
+ #: default so a dev tree without the manifest — or with a stale one after a manual wasm copy —
79
+ #: is not broken; the mismatch is still logged.
80
+ _ENFORCE_PROVENANCE_ENV = "INTENTUMDIFF_ENFORCE_WASM_PROVENANCE"
81
+
82
+
83
+ def _verify_builtin_provenance(path: Path) -> None:
84
+ """Verify a bundled first-party Wasm against the #89 provenance manifest, when present.
85
+
86
+ Parallels hub.py's third-party checksum path, but for the first-party bundled parsers: a
87
+ mismatch — or an artifact the manifest never saw (the #87 stale-artifact case) — is a
88
+ supply-chain red flag. It is logged as a warning, and raised as a ``PluginLoadError`` when
89
+ ``INTENTUMDIFF_ENFORCE_WASM_PROVENANCE=1``. A missing/unreadable manifest (a dev build without
90
+ the package-time provenance step) is skipped — verification is optional by design (#89).
91
+ """
92
+ if not _is_trusted_wasm_path(path) or not _PROVENANCE_MANIFEST.is_file():
93
+ return
94
+ try:
95
+ manifest = json.loads(_PROVENANCE_MANIFEST.read_text(encoding="utf-8"))
96
+ artifacts = manifest.get("artifacts", {})
97
+ except (OSError, ValueError):
98
+ return # unreadable manifest — do not block on a broken dev artifact
99
+ if not isinstance(artifacts, dict):
100
+ return
101
+ name = Path(path).name
102
+ expected = artifacts.get(name)
103
+ problem: str | None = None
104
+ if expected is None:
105
+ problem = f"bundled Wasm {name!r} is not listed in the provenance manifest"
106
+ else:
107
+ digest = hashlib.sha256(Path(path).read_bytes()).hexdigest()
108
+ if digest != expected.get("sha256"):
109
+ problem = f"bundled Wasm {name!r} does not match its provenance SHA-256"
110
+ if problem is None:
111
+ return
112
+ if os.environ.get(_ENFORCE_PROVENANCE_ENV) == "1":
113
+ raise PluginLoadError(str(path), problem)
114
+ logger.warning(
115
+ "Wasm provenance check: %s (set %s=1 to make this a hard failure).",
116
+ problem,
117
+ _ENFORCE_PROVENANCE_ENV,
118
+ )
119
+
120
+
121
+ def _check_wasmtime_version(
122
+ wasm_path: str | Path | None = None,
123
+ *,
124
+ trusted: bool = False,
125
+ ) -> None:
126
+ """Refuse to load plugins under known-vulnerable wasmtime versions.
127
+
128
+ wasmtime==44.0.0 is affected by CVE-2026-44216, which allows a malicious
129
+ Wasm module to panic the host process by allocating an extremely large
130
+ WebAssembly table under the default on-demand allocator with memory64.
131
+
132
+ The normal dependency path now requires a fixed Python binding
133
+ (wasmtime>=45.0). This offline runtime gate remains as defense-in-depth
134
+ for stale or manually pinned environments.
135
+
136
+ See: https://github.com/bytecodealliance/wasmtime/security/advisories/GHSA-p8xm-42r7-89xg
137
+ """
138
+ try:
139
+ version = _importlib_metadata.version("wasmtime")
140
+ except _importlib_metadata.PackageNotFoundError:
141
+ # wasmtime not installed as a proper package — skip version gate.
142
+ return
143
+
144
+ if version not in _VULNERABLE_WASMTIME_VERSIONS:
145
+ return
146
+
147
+ override = os.environ.get("INTENTUMDIFF_ALLOW_VULNERABLE_WASMTIME", "").strip()
148
+ if override in ("1", "true", "yes"):
149
+ logger.warning(
150
+ "INTENTUMDIFF_ALLOW_VULNERABLE_WASMTIME is set: loading Wasm plugin under "
151
+ "wasmtime==%s which is in the known-vulnerable blocklist (%s). "
152
+ "See: %s",
153
+ version,
154
+ _WASMTIME_ADVISORY,
155
+ _WASMTIME_ADVISORY_URL,
156
+ )
157
+ return
158
+
159
+ raise PluginLoadError(
160
+ "<wasmtime-version-check>",
161
+ f"wasmtime=={version} is in the known-vulnerable blocklist "
162
+ f"({_WASMTIME_ADVISORY} — host-process panic on large table allocation "
163
+ f"with memory64). Upgrade wasmtime or set INTENTUMDIFF_ALLOW_VULNERABLE_WASMTIME=1 "
164
+ f"to override (not recommended). Run 'intentumdiff security-check' for a live "
165
+ f"OSV scan. See: {_WASMTIME_ADVISORY_URL}",
166
+ )
167
+
168
+
169
+ # ---------------------------------------------------------------------------
170
+ # OSV advisory cache (once-per-day background fetch, API-friendly)
171
+ # ---------------------------------------------------------------------------
172
+ #
173
+ # Design: two separate files in the user cache directory.
174
+ #
175
+ # osv_cache.json — the actual OSV results (vuln list + checked_at)
176
+ # osv_last_fetch.stamp — epoch timestamp of the last *fetch attempt*
177
+ #
178
+ # The 24-hour rate limit is enforced by the STAMP file, not by the cache.
179
+ # Deleting osv_cache.json clears the displayed results but does NOT unlock
180
+ # a new fetch — the stamp still gates it. This prevents cache-delete loops
181
+ # from hammering the OSV API. The stamp is written BEFORE the network
182
+ # request so that even a failed/timed-out call counts against the budget.
183
+ #
184
+ # To force a manual refresh (e.g. from `intentumdiff security-check --refresh`):
185
+ # delete osv_last_fetch.stamp explicitly — that is the documented escape.
186
+
187
+ _OSV_FETCH_INTERVAL = 86_400 # 24 hours — one fetch per day, hard-coded
188
+
189
+ _PACKAGES_TO_AUDIT = (
190
+ "wasmtime",
191
+ "intentumdiff",
192
+ "fastapi",
193
+ "starlette",
194
+ "cryptography",
195
+ "defusedxml",
196
+ )
197
+
198
+
199
+ def _osv_dir() -> Path:
200
+ """Platform-appropriate cache directory for OSV advisory files."""
201
+ if os.name == "nt":
202
+ base = Path(os.environ.get("LOCALAPPDATA") or (Path.home() / "AppData" / "Local"))
203
+ else:
204
+ base = Path(os.environ.get("XDG_CACHE_HOME") or (Path.home() / ".cache"))
205
+ return base / "intentumdiff"
206
+
207
+
208
+ def _osv_cache_path() -> Path:
209
+ return _osv_dir() / "osv_cache.json"
210
+
211
+
212
+ def _osv_stamp_path() -> Path:
213
+ """Fetch-gate stamp — rate-limits OSV calls independently of the cache."""
214
+ return _osv_dir() / "osv_last_fetch.stamp"
215
+
216
+
217
+ def _read_stamp() -> float:
218
+ """Return the epoch time recorded in the stamp file, or 0.0 if absent."""
219
+ try:
220
+ return float(_osv_stamp_path().read_text(encoding="utf-8").strip())
221
+ except Exception:
222
+ return 0.0
223
+
224
+
225
+ def _write_stamp() -> None:
226
+ """Record the current time as the last fetch attempt (called BEFORE fetch)."""
227
+ p = _osv_stamp_path()
228
+ try:
229
+ p.parent.mkdir(parents=True, exist_ok=True)
230
+ p.write_text(str(_time.time()), encoding="utf-8")
231
+ except Exception:
232
+ logger.debug("Could not write OSV stamp file", exc_info=True)
233
+
234
+
235
+ def _load_osv_cache() -> list[dict] | None:
236
+ """Return cached vuln list if the cache file exists, else None."""
237
+ try:
238
+ data = json.loads(_osv_cache_path().read_text(encoding="utf-8"))
239
+ return data.get("vulns", [])
240
+ except Exception:
241
+ return None
242
+
243
+
244
+ def _save_osv_cache(vulns: list[dict]) -> None:
245
+ p = _osv_cache_path()
246
+ try:
247
+ p.parent.mkdir(parents=True, exist_ok=True)
248
+ p.write_text(
249
+ json.dumps({"checked_at": _time.time(), "vulns": vulns}, indent=2),
250
+ encoding="utf-8",
251
+ )
252
+ except Exception:
253
+ logger.debug("Could not save OSV advisory cache", exc_info=True)
254
+
255
+
256
+ def query_osv(packages: list[tuple[str, str]]) -> list[dict]:
257
+ """Query the OSV batch API for a list of (package, version) pairs.
258
+
259
+ Returns a flat list of finding dicts, each with keys:
260
+ package, version, id, aliases, summary.
261
+
262
+ Public so that ``intentumdiff security-check`` can call it directly.
263
+ Raises ``urllib.error.URLError`` or ``OSError`` on network failure.
264
+ """
265
+ queries = [
266
+ {"package": {"name": name, "ecosystem": "PyPI"}, "version": version}
267
+ for name, version in packages
268
+ ]
269
+ body = json.dumps({"queries": queries}).encode()
270
+ osv_url = "https://api.osv.dev/v1/querybatch"
271
+ if not osv_url.startswith("https://"): # defense-in-depth (#76 semgrep): urllib accepts file://
272
+ raise RuntimeError("OSV query URL must be https")
273
+ req = urllib.request.Request(
274
+ osv_url,
275
+ data=body,
276
+ headers={
277
+ "Content-Type": "application/json",
278
+ "User-Agent": "intentumdiff/osv-check",
279
+ },
280
+ method="POST",
281
+ )
282
+ ctx = ssl.create_default_context()
283
+ logger.info(
284
+ "OSV API request: querying %d package(s): %s",
285
+ len(packages),
286
+ ", ".join(f"{n}=={v}" for n, v in packages),
287
+ )
288
+ with urllib.request.urlopen(req, context=ctx, timeout=10) as resp: # nosemgrep: python.lang.security.audit.dynamic-urllib-use-detected.dynamic-urllib-use-detected -- literal https constant asserted above. noqa: S310 # nosec B310 - https scheme asserted above
289
+ data = json.loads(resp.read())
290
+ logger.info("OSV API response received (%d result(s))", len(data.get("results", [])))
291
+
292
+ vulns: list[dict] = []
293
+ for (pkg, ver), result in zip(packages, data.get("results", [])):
294
+ for v in result.get("vulns", []):
295
+ vulns.append({
296
+ "package": pkg,
297
+ "version": ver,
298
+ "id": v.get("id", ""),
299
+ "aliases": v.get("aliases", []),
300
+ "summary": v.get("summary", ""),
301
+ })
302
+ return vulns
303
+
304
+
305
+ def _log_osv_findings(vulns: list[dict], *, cached: bool) -> None:
306
+ tag = " (cached)" if cached else ""
307
+ for v in vulns:
308
+ pkg_ver = f"{v['package']}=={v['version']}"
309
+ aliases = ", ".join(v.get("aliases", []))
310
+ logger.warning(
311
+ "OSV advisory%s: %s affects %s — %s%s. "
312
+ "Run 'intentumdiff security-check' for details.",
313
+ tag,
314
+ v["id"],
315
+ pkg_ver,
316
+ v.get("summary", ""),
317
+ f" (also: {aliases})" if aliases else "",
318
+ )
319
+
320
+
321
+ def _collect_audit_packages() -> list[tuple[str, str]]:
322
+ """Return (package, version) pairs for all auditable installed packages."""
323
+ packages: list[tuple[str, str]] = []
324
+ for pkg in _PACKAGES_TO_AUDIT:
325
+ try:
326
+ packages.append((pkg, _importlib_metadata.version(pkg)))
327
+ except _importlib_metadata.PackageNotFoundError:
328
+ pass
329
+ return packages
330
+
331
+
332
+ def _osv_check_worker() -> None:
333
+ """Background daemon thread: write stamp, fetch OSV, save cache, log.
334
+
335
+ The stamp is written BEFORE the network call so that a timeout or
336
+ network failure still counts against the 24-hour budget. On failure,
337
+ no cache file is written, which is detectable by
338
+ ``_check_osv_cache_or_block()`` as a "known-failed fetch".
339
+ """
340
+ packages = _collect_audit_packages()
341
+ if not packages:
342
+ return
343
+
344
+ _write_stamp()
345
+ try:
346
+ vulns = query_osv(packages)
347
+ except Exception as exc:
348
+ logger.debug("OSV background check failed (network?): %s", exc)
349
+ # No cache written — the absent cache + fresh stamp signals failure.
350
+ return
351
+
352
+ _save_osv_cache(vulns)
353
+ if vulns:
354
+ _log_osv_findings(vulns, cached=False)
355
+
356
+
357
+ def refresh_osv_cache() -> list[dict]:
358
+ """Synchronously refresh the OSV advisory cache, bypassing the 24h gate.
359
+
360
+ Deletes the stamp file first, then performs a blocking OSV fetch, saves
361
+ the result, and returns the vuln list. Called by
362
+ ``intentumdiff security-check --refresh``.
363
+
364
+ Raises ``urllib.error.URLError`` or ``OSError`` on network failure.
365
+ The stamp is still written before the fetch so that a failure counts
366
+ against the rate limit (prevents rapid retry loops).
367
+ """
368
+ try:
369
+ _osv_stamp_path().unlink()
370
+ except FileNotFoundError:
371
+ pass
372
+
373
+ packages = _collect_audit_packages()
374
+ if not packages:
375
+ return []
376
+
377
+ _write_stamp()
378
+ vulns = query_osv(packages) # raises on network failure
379
+ _save_osv_cache(vulns)
380
+ return vulns
381
+
382
+
383
+ def _check_osv_cache_or_block(
384
+ wasm_path: str | Path | None = None,
385
+ *,
386
+ trusted: bool = False,
387
+ ) -> None:
388
+ """Sync gate at plugin-load time: block if the last OSV fetch failed.
389
+
390
+ Logic:
391
+ - Stamp absent / stale (>24h): proceed optimistically; background thread
392
+ will refresh. We have no reason to block.
393
+ - Stamp fresh + cache present: validate against cached advisories.
394
+ - Stamp fresh + cache ABSENT: last fetch failed within 24h. Block until
395
+ the user runs ``intentumdiff security-check --refresh`` or sets the env override.
396
+ """
397
+ stamp_age = _time.time() - _read_stamp()
398
+ if stamp_age >= _OSV_FETCH_INTERVAL:
399
+ # Stamp stale or absent — background thread will handle it.
400
+ return
401
+
402
+ cache = _load_osv_cache()
403
+ if cache is None:
404
+ # Stamp is fresh but no cache file: the last fetch failed.
405
+ override = os.environ.get("INTENTUMDIFF_ALLOW_VULNERABLE_WASMTIME", "").strip()
406
+ if override in ("1", "true", "yes"):
407
+ logger.warning(
408
+ "INTENTUMDIFF_ALLOW_VULNERABLE_WASMTIME: loading plugins with "
409
+ "unverified OSV status — last advisory fetch failed."
410
+ )
411
+ return
412
+ if trusted or _is_trusted_wasm_path(wasm_path):
413
+ logger.warning(
414
+ "Loading first-party trusted Wasm plugin with unverified OSV "
415
+ "status because the last advisory fetch failed. Third-party "
416
+ "plugins remain blocked without INTENTUMDIFF_ALLOW_VULNERABLE_WASMTIME=1."
417
+ )
418
+ return
419
+ raise PluginLoadError(
420
+ "<osv-check>",
421
+ "The OSV advisory check failed on its last attempt (network "
422
+ "unavailable?). Plugin loading is blocked to protect against "
423
+ "undetected vulnerabilities. Run 'intentumdiff security-check --refresh' "
424
+ "to retry, or set INTENTUMDIFF_ALLOW_VULNERABLE_WASMTIME=1 to bypass "
425
+ "(not recommended).",
426
+ )
427
+
428
+ # Cache is present — check for any wasmtime advisories in it.
429
+ try:
430
+ wasmtime_ver = _importlib_metadata.version("wasmtime")
431
+ except _importlib_metadata.PackageNotFoundError:
432
+ return
433
+
434
+ for v in cache:
435
+ if v.get("package") == "wasmtime" and v.get("version") == wasmtime_ver:
436
+ override = os.environ.get("INTENTUMDIFF_ALLOW_VULNERABLE_WASMTIME", "").strip()
437
+ if override in ("1", "true", "yes"):
438
+ logger.warning(
439
+ "INTENTUMDIFF_ALLOW_VULNERABLE_WASMTIME: loading plugins despite "
440
+ "OSV advisory %s for wasmtime==%s.",
441
+ v["id"],
442
+ wasmtime_ver,
443
+ )
444
+ return
445
+ aliases = ", ".join(v.get("aliases", []))
446
+ raise PluginLoadError(
447
+ "<osv-check>",
448
+ f"OSV advisory {v['id']}"
449
+ + (f" ({aliases})" if aliases else "")
450
+ + f" affects wasmtime=={wasmtime_ver}: {v.get('summary', '')}. "
451
+ "Upgrade wasmtime, run 'intentumdiff security-check --refresh' for "
452
+ "details, or set INTENTUMDIFF_ALLOW_VULNERABLE_WASMTIME=1 to bypass "
453
+ "(not recommended).",
454
+ )
455
+
456
+
457
+ # Module-level guard: fire the background thread at most once per process.
458
+ _osv_thread_lock = threading.Lock()
459
+ _osv_thread_started = False
460
+
461
+
462
+ def _maybe_start_osv_check() -> None:
463
+ """Start the async OSV background thread if the daily budget allows it.
464
+
465
+ - Stamp fresh + cache present → keep startup quiet, no network.
466
+ - Stamp fresh + cache absent → last fetch failed; ``_check_osv_cache_or_block``
467
+ already handled blocking; nothing more to do here.
468
+ - Stamp stale / absent → spawn daemon thread to refresh in the background.
469
+
470
+ The background thread is async (daemon) so it never blocks the caller.
471
+ Deleting osv_cache.json does NOT bypass the rate limit; only deleting
472
+ osv_last_fetch.stamp is the documented escape hatch.
473
+ """
474
+ global _osv_thread_started
475
+ with _osv_thread_lock:
476
+ if _osv_thread_started:
477
+ return
478
+
479
+ age = _time.time() - _read_stamp()
480
+ if age < _OSV_FETCH_INTERVAL:
481
+ # Stamp fresh: keep normal startup/tests quiet. The synchronous
482
+ # gate above still blocks vulnerable wasmtime, while explicit
483
+ # advisory visibility belongs to `intentumdiff security-check`.
484
+ cached = _load_osv_cache()
485
+ if cached:
486
+ logger.debug("OSV advisory cache has %d cached finding(s).", len(cached))
487
+ _osv_thread_started = True
488
+ return
489
+
490
+ # Stamp stale or absent: schedule an async background refresh.
491
+ t = threading.Thread(
492
+ target=_osv_check_worker,
493
+ daemon=True,
494
+ name="intentumdiff-osv-check",
495
+ )
496
+ t.start()
497
+ _osv_thread_started = True
498
+
499
+
500
+ # ---------------------------------------------------------------------------
501
+ # Host-side implementations of WIT host-utils imports
502
+ # ---------------------------------------------------------------------------
503
+
504
+ _HOST_UTILS_MAX_JSON_BYTES = 8 * 1024 * 1024
505
+ _HOST_UTILS_MAX_JSON_DEPTH = 256
506
+ # CST JSON is verbose: a supported 10k-line file can exceed 250k container and
507
+ # scalar JSON nodes while still fitting under the byte cap.
508
+ _HOST_UTILS_MAX_JSON_NODES = 1_000_000
509
+ _HOST_UTILS_MAX_TRIVIA_TYPES = 1_024
510
+ _HOST_UTILS_MAX_TRIVIA_TYPE_BYTES = 256
511
+ _HOST_UTILS_MAX_TRIVIA_BYTES = 64 * 1024
512
+ _HOST_UTILS_MAX_LOG_BYTES = 16 * 1024
513
+ _MAX_PLUGIN_OUTPUT_BYTES = 16 * 1024 * 1024
514
+ # Hard linear-memory cap per plugin store (issue #87): the output cap above is
515
+ # enforced post-hoc, so a pathological input (binary decoded as text) could
516
+ # transiently balloon guest memory far past it BEFORE the host measured. The
517
+ # store limiter bails DURING parse instead - a trap, classified as a sandbox
518
+ # violation like any other, and the tainted store reloads. Default is generous
519
+ # (grammar tables + tree + output for legit large sources); deployments can
520
+ # tighten via the env var.
521
+ _PLUGIN_MEMORY_LIMIT_ENV = "INTENTUMDIFF_PLUGIN_MEMORY_LIMIT_BYTES"
522
+ _DEFAULT_PLUGIN_MEMORY_LIMIT_BYTES = 192 * 1024 * 1024
523
+
524
+
525
+ def _plugin_memory_limit_bytes() -> int:
526
+ raw = os.environ.get(_PLUGIN_MEMORY_LIMIT_ENV, "")
527
+ try:
528
+ value = int(raw)
529
+ except ValueError:
530
+ return _DEFAULT_PLUGIN_MEMORY_LIMIT_BYTES
531
+ return value if value > 0 else _DEFAULT_PLUGIN_MEMORY_LIMIT_BYTES
532
+
533
+
534
+ def _host_utils_error(detail: str) -> ValueError:
535
+ return ValueError(f"host-utils input rejected: {detail}")
536
+
537
+
538
+ def _bounded_plugin_text(plugin_id: str, export_name: str, value: Any) -> str:
539
+ text = str(value)
540
+ size = len(text.encode("utf-8"))
541
+ if size > _MAX_PLUGIN_OUTPUT_BYTES:
542
+ raise PluginOutputError(
543
+ plugin_id,
544
+ f"{export_name} output is {size} bytes; limit is {_MAX_PLUGIN_OUTPUT_BYTES} bytes",
545
+ )
546
+ return text
547
+
548
+
549
+ def _check_json_text_limits(cst_json: str) -> None:
550
+ size = len(cst_json.encode("utf-8"))
551
+ if size > _HOST_UTILS_MAX_JSON_BYTES:
552
+ raise _host_utils_error(
553
+ f"JSON payload is {size} bytes; limit is "
554
+ f"{_HOST_UTILS_MAX_JSON_BYTES} bytes"
555
+ )
556
+
557
+ depth = 0
558
+ in_string = False
559
+ escaped = False
560
+ for ch in cst_json:
561
+ if in_string:
562
+ if escaped:
563
+ escaped = False
564
+ elif ch == "\\":
565
+ escaped = True
566
+ elif ch == '"':
567
+ in_string = False
568
+ continue
569
+ if ch == '"':
570
+ in_string = True
571
+ elif ch in "[{":
572
+ depth += 1
573
+ if depth > _HOST_UTILS_MAX_JSON_DEPTH:
574
+ raise _host_utils_error(
575
+ f"JSON nesting depth exceeds {_HOST_UTILS_MAX_JSON_DEPTH}"
576
+ )
577
+ elif ch in "]}":
578
+ depth = max(0, depth - 1)
579
+
580
+
581
+ def _check_trivia_type_limits(trivia_types: list[str]) -> None:
582
+ if len(trivia_types) > _HOST_UTILS_MAX_TRIVIA_TYPES:
583
+ raise _host_utils_error(
584
+ f"trivia type count is {len(trivia_types)}; limit is "
585
+ f"{_HOST_UTILS_MAX_TRIVIA_TYPES}"
586
+ )
587
+
588
+ total = 0
589
+ for trivia_type in trivia_types:
590
+ size = len(str(trivia_type).encode("utf-8"))
591
+ if size > _HOST_UTILS_MAX_TRIVIA_TYPE_BYTES:
592
+ raise _host_utils_error(
593
+ f"trivia type is {size} bytes; limit is "
594
+ f"{_HOST_UTILS_MAX_TRIVIA_TYPE_BYTES} bytes"
595
+ )
596
+ total += size
597
+ if total > _HOST_UTILS_MAX_TRIVIA_BYTES:
598
+ raise _host_utils_error(
599
+ f"trivia type payload is {total} bytes; limit is "
600
+ f"{_HOST_UTILS_MAX_TRIVIA_BYTES} bytes"
601
+ )
602
+
603
+
604
+ def _truncate_utf8(text: str, max_bytes: int) -> str:
605
+ encoded = text.encode("utf-8")
606
+ if len(encoded) <= max_bytes:
607
+ return text
608
+ marker = b"...[truncated]"
609
+ budget = max(0, max_bytes - len(marker))
610
+ return encoded[:budget].decode("utf-8", errors="ignore") + marker.decode("ascii")
611
+
612
+
613
+ def _load_limited_cst_json(cst_json: str) -> Any:
614
+ _check_json_text_limits(cst_json)
615
+ try:
616
+ data = json.loads(cst_json)
617
+ except json.JSONDecodeError as exc:
618
+ raise _host_utils_error(f"invalid JSON: {exc.msg}") from exc
619
+
620
+ stack: list[tuple[Any, int]] = [(data, 1)]
621
+ count = 0
622
+ while stack:
623
+ node, depth = stack.pop()
624
+ count += 1
625
+ if count > _HOST_UTILS_MAX_JSON_NODES:
626
+ raise _host_utils_error(
627
+ f"JSON node count exceeds {_HOST_UTILS_MAX_JSON_NODES}"
628
+ )
629
+ if depth > _HOST_UTILS_MAX_JSON_DEPTH:
630
+ raise _host_utils_error(
631
+ f"JSON nesting depth exceeds {_HOST_UTILS_MAX_JSON_DEPTH}"
632
+ )
633
+ if isinstance(node, dict):
634
+ stack.extend((value, depth + 1) for value in node.values())
635
+ elif isinstance(node, list):
636
+ stack.extend((value, depth + 1) for value in node)
637
+ return data
638
+
639
+
640
+ def _strip_trivia_impl(cst_json: str, trivia_types: list[str]) -> str:
641
+ """Remove trivia nodes from a bounded CST JSON document."""
642
+ _check_trivia_type_limits(trivia_types)
643
+ trivia_set = set(trivia_types)
644
+ data = _load_limited_cst_json(cst_json)
645
+ if not isinstance(data, dict):
646
+ return json.dumps(data, separators=(",", ":"), ensure_ascii=False)
647
+
648
+ results: dict[int, Any] = {}
649
+ stack: list[tuple[Any, bool]] = [(data, False)]
650
+ while stack:
651
+ node, visited = stack.pop()
652
+ if not isinstance(node, dict):
653
+ results[id(node)] = node
654
+ continue
655
+ if not visited:
656
+ stack.append((node, True))
657
+ children = node.get("children")
658
+ if isinstance(children, list):
659
+ stack.extend((child, False) for child in reversed(children))
660
+ continue
661
+ if node.get("type") in trivia_set:
662
+ results[id(node)] = None
663
+ continue
664
+ children = node.get("children")
665
+ if isinstance(children, list):
666
+ filtered = [
667
+ results[id(child)]
668
+ for child in children
669
+ if results.get(id(child)) is not None
670
+ ]
671
+ results[id(node)] = dict(node, children=filtered)
672
+ else:
673
+ results[id(node)] = node
674
+
675
+ result = results[id(data)]
676
+ return json.dumps(result, separators=(",", ":"), ensure_ascii=False)
677
+
678
+
679
+ def _structural_hash_impl(cst_json: str) -> str:
680
+ """
681
+ Compute a structural hash of a CST node (JSON object).
682
+
683
+ Algorithm matches the engine: SHA-256, hex-encoded.
684
+ leaf: sha256(type + ":" + text)
685
+ internal: sha256(type + "|" + "|".join(hash(child) for child in children))
686
+ """
687
+
688
+ data = _load_limited_cst_json(cst_json)
689
+ hashes: dict[int, str] = {}
690
+ stack: list[tuple[Any, bool]] = [(data, False)]
691
+ while stack:
692
+ node, visited = stack.pop()
693
+ if not isinstance(node, dict):
694
+ hashes[id(node)] = hashlib.sha256(str(node).encode()).hexdigest()
695
+ continue
696
+ children = node.get("children")
697
+ has_children = isinstance(children, list) and bool(children)
698
+ if has_children and not visited:
699
+ stack.append((node, True))
700
+ stack.extend((child, False) for child in reversed(children))
701
+ continue
702
+ # Accept BOTH key spellings (#49 item 2, latent bug): CST nodes carry
703
+ # type/text, but FullParse SemanticNode trees carry node_type/label — the
704
+ # old type/text-only reads hashed FullParse trees as all-blank SHAPE.
705
+ node_type = node.get("node_type") or node.get("type", "")
706
+ if has_children:
707
+ child_hashes = "|".join(hashes[id(c)] for c in children)
708
+ payload = f"{node_type}|{child_hashes}"
709
+ else:
710
+ text = node.get("label", node.get("text", ""))
711
+ payload = f"{node_type}:{text}"
712
+ hashes[id(node)] = hashlib.sha256(payload.encode()).hexdigest()
713
+ return hashes[id(data)]
714
+
715
+
716
+ def _log_impl(level: str, message: str) -> None:
717
+ lvl = getattr(logging, level.upper(), logging.DEBUG)
718
+ logger.log(lvl, "[plugin] %s", _truncate_utf8(str(message), _HOST_UTILS_MAX_LOG_BYTES))
719
+
720
+
721
+ def _record_field(record: Any, *names: str) -> Any:
722
+ for name in names:
723
+ if isinstance(record, dict) and name in record:
724
+ return record[name]
725
+ if hasattr(record, name):
726
+ return getattr(record, name)
727
+ attr = name.replace("-", "_")
728
+ if hasattr(record, attr):
729
+ return getattr(record, attr)
730
+ return None
731
+
732
+
733
+ def _language_info_record_to_dict(record: Any) -> dict[str, Any]:
734
+ """Convert a WIT ``language-info`` record into a Python dict."""
735
+ return {
736
+ "language_id": str(_record_field(record, "language-id", "language_id") or ""),
737
+ "language_name": str(_record_field(record, "language-name", "language_name") or ""),
738
+ "language_short_name": str(
739
+ _record_field(record, "language-short-name", "language_short_name") or ""
740
+ ),
741
+ "monaco_language": str(_record_field(record, "monaco-language", "monaco_language") or ""),
742
+ "default_filename": str(
743
+ _record_field(record, "default-filename", "default_filename") or ""
744
+ ),
745
+ "language_file_extensions": list(
746
+ _record_field(
747
+ record,
748
+ "language-file-extensions",
749
+ "language_file_extensions",
750
+ )
751
+ or []
752
+ ),
753
+ "author": str(_record_field(record, "author") or ""),
754
+ "plugin_version": str(_record_field(record, "plugin-version", "plugin_version") or ""),
755
+ "last_updated": str(_record_field(record, "last-updated", "last_updated") or ""),
756
+ }
757
+
758
+
759
+ # ---------------------------------------------------------------------------
760
+ # Loaded plugin wrapper
761
+ # ---------------------------------------------------------------------------
762
+
763
+
764
+ class LoadedPlugin:
765
+ """
766
+ Wraps a wasmtime-instantiated Wasm component.
767
+
768
+ All public methods translate Wasm traps into typed Python exceptions.
769
+ """
770
+
771
+ # Qualified interface export names as emitted by wit-bindgen
772
+ _PARSER_IFACE = "intentdiff:plugin/parser@1.0.0"
773
+ _RENDERER_IFACE = "intentdiff:plugin/renderer@1.0.0"
774
+ _ENRICHER_IFACE = "intentdiff:plugin/enricher@1.0.0"
775
+ _DIFF_ANALYZER_IFACE = "intentdiff:plugin/diff-analyzer@1.0.0"
776
+
777
+ def __init__(
778
+ self,
779
+ wasm_path: str,
780
+ instance: Any,
781
+ store: Store,
782
+ fuel: int,
783
+ iface_name: str,
784
+ trusted: bool = False,
785
+ ) -> None:
786
+ self._wasm_path = wasm_path
787
+ self._instance = instance
788
+ self._store = store
789
+ self._fuel = fuel
790
+ self._iface_name = iface_name
791
+ self._trusted = trusted
792
+ # Cache the interface-level ExportIndex for nested function lookups
793
+ self._iface_idx = instance.get_export_index(store, iface_name)
794
+ # Wasm Store is not thread-safe; serialise all calls through this lock.
795
+ self._lock = threading.Lock()
796
+ # Set to True after any Wasm trap; triggers a fresh instantiation on
797
+ # the next call so one bad file doesn't poison subsequent ones.
798
+ self._tainted = False
799
+ self._telemetry: list[dict[str, Any]] = []
800
+
801
+ @property
802
+ def wasm_path(self) -> str:
803
+ """Path of the ``.wasm`` file that backs this plugin instance."""
804
+ return self._wasm_path
805
+
806
+ @property
807
+ def trusted(self) -> bool:
808
+ """True when the plugin was loaded through a trusted first-party path."""
809
+ return self._trusted
810
+
811
+ def drain_telemetry(self) -> list[dict[str, Any]]:
812
+ """Return and clear bounded Wasm-call telemetry for this plugin."""
813
+ with self._lock:
814
+ records = list(self._telemetry)
815
+ self._telemetry.clear()
816
+ return records
817
+
818
+ # ── Parser calls ────────────────────────────────────────────────────────
819
+
820
+ def call_parser_mode(self) -> str:
821
+ raw = self._call("get-parser-mode")
822
+ # Component Model enums come back as integers; map to string
823
+ _mode_map = {0: "interpret-cst", 1: "full-parse"}
824
+ if isinstance(raw, int):
825
+ return _mode_map.get(raw, "interpret-cst")
826
+ return str(raw)
827
+
828
+ def call_grammar_id(self) -> str:
829
+ return _bounded_plugin_text(self._wasm_path, "grammar-id", self._call("grammar-id"))
830
+
831
+ def call_detect_language(self, filename: str, content: str) -> str:
832
+ return _bounded_plugin_text(
833
+ self._wasm_path,
834
+ "detect-language",
835
+ self._call("detect-language", filename, content),
836
+ )
837
+
838
+ def call_process(
839
+ self,
840
+ input_: str,
841
+ language: str,
842
+ filename: str,
843
+ fuel: int | None = None,
844
+ ) -> str:
845
+ return _bounded_plugin_text(
846
+ self._wasm_path,
847
+ "process",
848
+ self._call("process", input_, language, filename, fuel_override=fuel),
849
+ )
850
+
851
+ def call_trivia_node_types(self) -> list[str]:
852
+ result = self._call("trivia-node-types")
853
+ return list(result) if result is not None else []
854
+
855
+ def call_language_ids(self) -> list[str]:
856
+ result = self._call("language-ids")
857
+ return list(result) if result is not None else []
858
+
859
+ def call_language_info(self) -> list[dict[str, Any]]:
860
+ """Return plugin-owned language metadata when the export exists."""
861
+ if not self._has_export("language-info"):
862
+ return []
863
+ result = self._call("language-info")
864
+ if result is None:
865
+ return []
866
+ return [_language_info_record_to_dict(item) for item in list(result)]
867
+
868
+ def call_priority(self, iface: str = "parser") -> int:
869
+ return int(self._call("priority"))
870
+
871
+ def call_preprocess_source(self, source: str) -> str:
872
+ return _bounded_plugin_text(
873
+ self._wasm_path,
874
+ "preprocess-source",
875
+ self._call("preprocess-source", source),
876
+ )
877
+
878
+ def call_example(self, language: str) -> dict[str, str]:
879
+ result = self._call("example", language)
880
+ if result is None:
881
+ return {"old": "", "new": ""}
882
+ # wasmtime returns WIT records as objects with field attributes
883
+ if hasattr(result, "old"):
884
+ return {"old": str(result.old), "new": str(result.new)}
885
+ if isinstance(result, (tuple, list)) and len(result) >= 2:
886
+ return {"old": str(result[0]), "new": str(result[1])}
887
+ if isinstance(result, dict):
888
+ return {"old": str(result.get("old", "")), "new": str(result.get("new", ""))}
889
+ return {"old": "", "new": ""}
890
+
891
+ # ── Enricher calls ──────────────────────────────────────────────────────
892
+
893
+ def call_enrich(
894
+ self,
895
+ tree_json: str,
896
+ raw_source: str,
897
+ language: str,
898
+ filename: str,
899
+ fuel: int | None = None,
900
+ ) -> str:
901
+ return _bounded_plugin_text(
902
+ self._wasm_path,
903
+ "enrich",
904
+ self._call(
905
+ "enrich",
906
+ tree_json,
907
+ raw_source,
908
+ language,
909
+ filename,
910
+ fuel_override=fuel,
911
+ ),
912
+ )
913
+
914
+ # ── Diff-analyzer calls ─────────────────────────────────────────────────
915
+
916
+ def call_analyze_diff(
917
+ self, diff_json: str, language: str, filename: str, fuel: int | None = None
918
+ ) -> str:
919
+ return _bounded_plugin_text(
920
+ self._wasm_path,
921
+ "analyze-diff",
922
+ self._call("analyze-diff", diff_json, language, filename, fuel_override=fuel),
923
+ )
924
+
925
+ # ── Renderer calls ──────────────────────────────────────────────────────
926
+
927
+ def call_format_name(self) -> str:
928
+ return _bounded_plugin_text(self._wasm_path, "format-name", self._call("format-name"))
929
+
930
+ def call_render(self, diff_json: str, fuel: int | None = None) -> str:
931
+ return _bounded_plugin_text(
932
+ self._wasm_path,
933
+ "render",
934
+ self._call("render", diff_json, fuel_override=fuel),
935
+ )
936
+
937
+ def call_supported_options(self) -> list[str]:
938
+ result = self._call("supported-options")
939
+ return list(result) if result is not None else []
940
+
941
+ # ── Internal ────────────────────────────────────────────────────────────
942
+
943
+ def _reload(self) -> None:
944
+ """Recreate the Wasm store and instance after a trap (called with lock held)."""
945
+ logger.debug("Reloading Wasm plugin %r after trap", self._wasm_path)
946
+ fresh = load_plugin(self._wasm_path, self._fuel, trusted=self._trusted)
947
+ self._instance = fresh._instance
948
+ self._store = fresh._store
949
+ self._iface_idx = fresh._instance.get_export_index(fresh._store, self._iface_name)
950
+ self._tainted = False
951
+
952
+ def _call(self, func_name: str, *args: Any, fuel_override: int | None = None) -> Any:
953
+ """Call a component export by name (kebab-case), within the plugin interface."""
954
+ with self._lock:
955
+ return self._call_locked(func_name, *args, fuel_override=fuel_override)
956
+
957
+ def _has_export(self, func_name: str) -> bool:
958
+ """Return whether the current plugin interface exposes *func_name*."""
959
+ with self._lock:
960
+ if self._tainted:
961
+ self._reload()
962
+ return (
963
+ self._instance.get_export_index(
964
+ self._store, func_name, self._iface_idx
965
+ )
966
+ is not None
967
+ )
968
+
969
+ def _call_locked(self, func_name: str, *args: Any, fuel_override: int | None = None) -> Any:
970
+ """Internal: called with self._lock held."""
971
+ if self._tainted:
972
+ self._reload()
973
+
974
+ fuel = fuel_override if fuel_override is not None else self._fuel
975
+ unlimited = fuel == -1
976
+ started = _time.perf_counter()
977
+ status = "ok"
978
+ remaining: int | None = None
979
+ consumed: int | None = None
980
+ if not unlimited:
981
+ try:
982
+ self._store.set_fuel(fuel)
983
+ except WasmtimeError:
984
+ status = "fuel_set_failed"
985
+ logger.warning(
986
+ "set_fuel failed for plugin %r — fuel cap may not be active",
987
+ self._wasm_path,
988
+ )
989
+
990
+ try:
991
+ # Two-level lookup: interface instance → function
992
+ fn_idx = self._instance.get_export_index(
993
+ self._store, func_name, self._iface_idx
994
+ )
995
+ if fn_idx is None:
996
+ raise PluginSandboxViolation(
997
+ self._wasm_path,
998
+ f"export '{func_name}' not found in '{self._iface_name}'",
999
+ )
1000
+ fn = self._instance.get_func(self._store, fn_idx)
1001
+ if fn is None:
1002
+ raise PluginSandboxViolation(
1003
+ self._wasm_path, f"export '{func_name}' is not a function"
1004
+ )
1005
+ result = fn(self._store, *args)
1006
+ if not unlimited:
1007
+ remaining = self._store.get_fuel()
1008
+ consumed = fuel - remaining
1009
+ logger.debug(
1010
+ "Plugin %r: %r consumed %d instructions (budget %d, %.1f%% used)",
1011
+ self._wasm_path,
1012
+ func_name,
1013
+ consumed,
1014
+ fuel,
1015
+ consumed / fuel * 100,
1016
+ )
1017
+ return result
1018
+ except PluginFuelExhausted:
1019
+ status = "fuel_exhausted"
1020
+ self._tainted = True
1021
+ raise
1022
+ except PluginSandboxViolation:
1023
+ status = "sandbox_violation"
1024
+ self._tainted = True
1025
+ raise
1026
+ except WasmtimeError as exc:
1027
+ self._tainted = True
1028
+ msg = str(exc)
1029
+ if "fuel" in msg.lower() or "out of fuel" in msg.lower():
1030
+ status = "fuel_exhausted"
1031
+ raise PluginFuelExhausted(self._wasm_path, fuel) from exc
1032
+ if "memory" in msg.lower() and ("limit" in msg.lower() or "grow" in msg.lower()):
1033
+ # The issue-#87 store limiter fired mid-parse (early output
1034
+ # bounding) - still a sandbox violation, but named for triage.
1035
+ status = "memory_limit"
1036
+ raise PluginSandboxViolation(
1037
+ self._wasm_path,
1038
+ f"linear memory limit hit during {func_name}: {msg}",
1039
+ ) from exc
1040
+ status = "wasmtime_error"
1041
+ # Treat all other wasmtime errors (traps, bad-parameter, etc.) as
1042
+ # sandbox violations so they are classified consistently.
1043
+ raise PluginSandboxViolation(self._wasm_path, msg) from exc
1044
+ except Exception as exc:
1045
+ status = "exception"
1046
+ self._tainted = True
1047
+ raise PluginSandboxViolation(self._wasm_path, str(exc)) from exc
1048
+ finally:
1049
+ elapsed_ms = (_time.perf_counter() - started) * 1000.0
1050
+ if not unlimited and remaining is None:
1051
+ try:
1052
+ remaining = self._store.get_fuel()
1053
+ consumed = fuel - remaining
1054
+ except Exception:
1055
+ remaining = None
1056
+ consumed = None
1057
+ self._record_telemetry(
1058
+ func_name=func_name,
1059
+ fuel_budget=fuel,
1060
+ fuel_unlimited=unlimited,
1061
+ fuel_consumed=consumed,
1062
+ fuel_remaining=remaining,
1063
+ elapsed_ms=elapsed_ms,
1064
+ status=status,
1065
+ args=args,
1066
+ )
1067
+
1068
+ def _record_telemetry(
1069
+ self,
1070
+ *,
1071
+ func_name: str,
1072
+ fuel_budget: int,
1073
+ fuel_unlimited: bool,
1074
+ fuel_consumed: int | None,
1075
+ fuel_remaining: int | None,
1076
+ elapsed_ms: float,
1077
+ status: str,
1078
+ args: tuple[Any, ...] = (),
1079
+ ) -> None:
1080
+ input_bytes: int | None = None
1081
+ input_lines: int | None = None
1082
+ language: str | None = None
1083
+ filename: str | None = None
1084
+ if func_name == "process" and len(args) >= 3:
1085
+ source = args[0]
1086
+ if isinstance(source, str):
1087
+ input_bytes = len(source.encode("utf-8"))
1088
+ input_lines = len(source.splitlines()) or (1 if source else 0)
1089
+ if isinstance(args[1], str):
1090
+ language = args[1]
1091
+ if isinstance(args[2], str):
1092
+ filename = args[2]
1093
+ record = {
1094
+ "plugin": str(self._wasm_path),
1095
+ "interface": self._iface_name,
1096
+ "function": func_name,
1097
+ "engine_owner": "python",
1098
+ "engine": "python_wasmtime_plugin_host",
1099
+ "provenance": "first_party_wasm" if self._trusted else "third_party_wasm",
1100
+ "trusted": self._trusted,
1101
+ "status": status,
1102
+ "fuel_budget": None if fuel_unlimited else fuel_budget,
1103
+ "fuel_consumed": fuel_consumed,
1104
+ "fuel_remaining": fuel_remaining,
1105
+ "fuel_used_percent": (
1106
+ None
1107
+ if fuel_unlimited or fuel_budget <= 0 or fuel_consumed is None
1108
+ else round(fuel_consumed / fuel_budget * 100.0, 3)
1109
+ ),
1110
+ "elapsed_ms": round(elapsed_ms, 3),
1111
+ }
1112
+ if language is not None:
1113
+ record["language"] = language
1114
+ if filename is not None:
1115
+ record["filename"] = filename
1116
+ if input_bytes is not None:
1117
+ record["input_bytes"] = input_bytes
1118
+ if input_lines is not None:
1119
+ record["input_lines"] = input_lines
1120
+ self._telemetry.append(record)
1121
+ if len(self._telemetry) > _MAX_TELEMETRY_RECORDS:
1122
+ del self._telemetry[: len(self._telemetry) - _MAX_TELEMETRY_RECORDS]
1123
+
1124
+
1125
+ # ---------------------------------------------------------------------------
1126
+ # Loader
1127
+ # ---------------------------------------------------------------------------
1128
+
1129
+
1130
+ def load_plugin(
1131
+ wasm_path: str | Path,
1132
+ fuel: int = 10_000_000,
1133
+ *,
1134
+ trusted: bool = False,
1135
+ ) -> LoadedPlugin:
1136
+ """
1137
+ Instantiate a Wasm component plugin with an empty WASI sandbox.
1138
+
1139
+ Parameters
1140
+ ----------
1141
+ wasm_path:
1142
+ Filesystem path to the compiled ``.wasm`` file.
1143
+ fuel:
1144
+ Maximum Wasm instructions before the engine traps. Pass ``-1``
1145
+ (``FUEL_UNLIMITED``) to disable the cap entirely — useful when
1146
+ indexing very large files. A warning is emitted at load time.
1147
+ trusted:
1148
+ Whether this plugin is a first-party trusted package asset. This can
1149
+ still affect unavailable-OSV-cache handling, but it does not bypass a
1150
+ known-vulnerable Wasmtime version.
1151
+ """
1152
+ _unlimited = fuel == -1
1153
+ path = Path(wasm_path)
1154
+ trusted = trusted or _is_trusted_wasm_path(path)
1155
+ _verify_builtin_provenance(path) # #89 first-party provenance (optional)
1156
+ _check_wasmtime_version(path, trusted=trusted) # fast sync blocklist
1157
+ _check_osv_cache_or_block(path, trusted=trusted) # fast sync OSV gate
1158
+ _maybe_start_osv_check() # async refresh
1159
+
1160
+ if not path.exists():
1161
+ raise PluginLoadError(str(path), "file not found")
1162
+
1163
+ try:
1164
+ cfg = Config()
1165
+ cfg.consume_fuel = not _unlimited # disabled → no cap, no tracking
1166
+ # CVE-2026-44216 mitigation: disable memory64 if the Python binding
1167
+ # exposes the setter (added in wasmtime-py post-44.0.0 builds).
1168
+ if hasattr(cfg, "wasm_memory64"):
1169
+ cfg.wasm_memory64 = False # type: ignore[attr-defined]
1170
+ if _unlimited:
1171
+ logger.warning(
1172
+ "Unlimited Wasm fuel for plugin %r — calls are uncapped and "
1173
+ "may run indefinitely.",
1174
+ str(wasm_path),
1175
+ )
1176
+ engine = Engine(cfg)
1177
+
1178
+ component = Component.from_file(engine, str(path))
1179
+
1180
+ linker = Linker(engine)
1181
+ linker.add_wasip2()
1182
+
1183
+ # Register host-utils imports using add_instance context manager.
1184
+ # root must be closed before instantiate() is called.
1185
+ root = linker.root()
1186
+ with root.add_instance("intentdiff:plugin/host-utils") as host:
1187
+ host.add_func(
1188
+ "strip-trivia",
1189
+ lambda store, args: _strip_trivia_impl(args[0], list(args[1])),
1190
+ )
1191
+ host.add_func(
1192
+ "structural-hash",
1193
+ lambda store, args: _structural_hash_impl(args[0]),
1194
+ )
1195
+ host.add_func(
1196
+ "log",
1197
+ lambda store, args: _log_impl(args[0], args[1]),
1198
+ )
1199
+ root.close()
1200
+
1201
+ wasi_cfg = WasiConfig()
1202
+ # Zero capabilities: no dirs, no env, no args, no stdio
1203
+
1204
+ store: Store = Store(engine)
1205
+ store.set_wasi(wasi_cfg)
1206
+ # Early output/memory bounding (issue #87): bail DURING parse, not
1207
+ # after the balloon.
1208
+ store.set_limits(memory_size=_plugin_memory_limit_bytes())
1209
+ if not _unlimited:
1210
+ store.set_fuel(fuel)
1211
+
1212
+ instance = linker.instantiate(store, component)
1213
+
1214
+ # Detect whether this is a parser, renderer, or enricher plugin
1215
+ if instance.get_export_index(store, LoadedPlugin._PARSER_IFACE) is not None:
1216
+ iface_name = LoadedPlugin._PARSER_IFACE
1217
+ elif instance.get_export_index(store, LoadedPlugin._RENDERER_IFACE) is not None:
1218
+ iface_name = LoadedPlugin._RENDERER_IFACE
1219
+ elif instance.get_export_index(store, LoadedPlugin._ENRICHER_IFACE) is not None:
1220
+ iface_name = LoadedPlugin._ENRICHER_IFACE
1221
+ elif instance.get_export_index(store, LoadedPlugin._DIFF_ANALYZER_IFACE) is not None:
1222
+ iface_name = LoadedPlugin._DIFF_ANALYZER_IFACE
1223
+ else:
1224
+ raise PluginLoadError(
1225
+ str(path),
1226
+ "component exports neither parser, renderer, enricher, nor diff-analyzer interface",
1227
+ )
1228
+
1229
+ return LoadedPlugin(
1230
+ str(path),
1231
+ instance,
1232
+ store,
1233
+ fuel,
1234
+ iface_name,
1235
+ trusted=trusted,
1236
+ )
1237
+
1238
+ except (PluginLoadError, PluginSandboxViolation):
1239
+ raise
1240
+ except WasmtimeError as exc:
1241
+ # Since the wasmtime 47 binding, INSTANTIATION charges fuel too, so a small
1242
+ # budget can trap before the component ever parses anything. Classify that the
1243
+ # same way _call_locked classifies a mid-parse trap: a typed PluginFuelExhausted,
1244
+ # not a generic load failure. Left as PluginLoadError, the registry would skip
1245
+ # the candidate and surface PluginNotFoundError('unknown') — reporting a fuel
1246
+ # problem as a missing-plugin problem.
1247
+ msg = str(exc)
1248
+ if "fuel" in msg.lower():
1249
+ raise PluginFuelExhausted(str(path), fuel, context="during instantiation") from exc
1250
+ raise PluginLoadError(str(path), msg) from exc
1251
+ except Exception as exc:
1252
+ raise PluginLoadError(str(path), str(exc)) from exc