Skip to content

The agent that grows with you

fix(plugins): Desktop lint stops flagging a bundled library's own classes

Tekniumf8fc25a8692e
diff --git a/hermes_cli/plugin_validate_desktop.py b/hermes_cli/plugin_validate_desktop.py
index c5915012a46..ee217f198b3 100644
--- a/hermes_cli/plugin_validate_desktop.py
+++ b/hermes_cli/plugin_validate_desktop.py
@@ -14,9 +14,10 @@ from pathlib import Path
from typing import List, Tuple
# (rule, regex) applied to comment-stripped source; every hit fails the "desktop surface" check.
+# ``X.prototype.y =`` is checked separately (``_foreign_prototype_writes``): it fails only when ``X``
+# is not a class/function the file declares itself, because a bundled library setting fields on its
+# own classes (three.js: ``Vector2.prototype.isVector2 = true``) is not reaching into the renderer.
_FORBIDDEN: tuple[tuple[str, re.Pattern[str]], ...] = (
- ("prototype patching",
- re.compile(r"\b[A-Za-z_$][\w$]*\.prototype\.[\w$]+\s*=[^=]")),
("prototype patching",
re.compile(r"\bObject\.definePropert(?:y|ies)\(\s*[\w$.]+\.prototype\b")),
("prototype patching",
@@ -79,11 +80,34 @@ def _mask_regex_literals(source: str) -> str:
return _REGEXP_CTOR_MATCHER.sub(lambda m: " " * len(m.group(0)), masked)
+_PROTOTYPE_WRITE = re.compile(r"\b([A-Za-z_$][\w$]*)\.prototype\.[\w$]+\s*=[^=]")
+# ``class X``/``function X`` anywhere, plus ``Y = class [X]`` / ``Y = function [X]`` (bundlers emit
+# ``var Vector2 = class _Vector2 {...}`` and the methods then write ``_Vector2.prototype``).
+_DECLARED_NAME = re.compile(
+ r"(?<![\w$.])([A-Za-z_$][\w$]*)\s*=\s*(?:class|function)\b(?:\s+([A-Za-z_$][\w$]*))?"
+ r"|\b(?:class|function)\s+([A-Za-z_$][\w$]*)")
+# A regex cannot see scope, so a same-named local declaration elsewhere in the file must not excuse
+# a write to a renderer global: these receivers always fail, declared or not.
+_RENDERER_GLOBAL = re.compile(
+ r"^(?:Object|Function|Array|String|Number|Boolean|Symbol|Promise|RegExp|Date|Error|JSON|Map|Set"
+ r"|WeakMap|WeakSet|Proxy|Reflect|Storage|Window|Document|Node|EventTarget|Event|Location|History"
+ r"|Navigator|WebSocket|XMLHttpRequest|Request|Response|Headers|URL|Blob|File|FileReader"
+ r"|MutationObserver|Worker|BroadcastChannel|MessagePort|IDB\w*|\w*Element|\w*Event|CSS\w*)$")
+
+
+def _foreign_prototype_writes(source: str) -> list[int]:
+ """Offsets of ``X.prototype.y =`` where ``X`` is a renderer global or not declared in the file."""
+ declared = {name for names in _DECLARED_NAME.findall(source) for name in names if name}
+ return [m.start() for m in _PROTOTYPE_WRITE.finditer(source)
+ if m.group(1) not in declared or _RENDERER_GLOBAL.match(m.group(1))]
+
+
def desktop_surface_findings(source: str) -> list[tuple[str, int]]:
"""Return ``[(rule, line)]`` for every forbidden construct in a plugin.js source."""
stripped = _strip_comments(source)
no_regex = _mask_regex_literals(stripped)
- findings: list[tuple[str, int]] = []
+ findings = [("prototype patching", stripped.count("\n", 0, at) + 1)
+ for at in _foreign_prototype_writes(stripped)]
for rule, pattern in _FORBIDDEN:
haystack = no_regex if rule in _MARKUP_RULES else stripped
for match in pattern.finditer(haystack):
diff --git a/plugin-catalog/README.md b/plugin-catalog/README.md
index ffdea34d73e..21d2320bb03 100644
--- a/plugin-catalog/README.md
+++ b/plugin-catalog/README.md
@@ -48,7 +48,9 @@ meaningful:
8. **Desktop plugins stay inside the SDK surface.** A `desktop/plugin.js` runs
in the Desktop renderer with the app's full authority (the loader isolates
errors, not capabilities), so a listed one may only use the plugin SDK:
- no prototype patching (`X.prototype.y =`, `Object.defineProperty(...prototype`),
+ no prototype patching of renderer or browser objects (`Storage.prototype.y =`,
+ `Object.defineProperty(...prototype`); a bundled library setting fields on
+ classes it declares itself (three.js and the like) is fine,
no `eval`/`new Function`, no `import()` of anything but `@hermes/plugin-sdk`
/ `react` (app bundle chunks, blob or http URLs included), no script-tag
injection, no reaching into the app's internal stores or its own markup
diff --git a/tests/hermes_cli/test_plugin_validate.py b/tests/hermes_cli/test_plugin_validate.py
index a2fddfe1d3e..44e2be0a230 100644
--- a/tests/hermes_cli/test_plugin_validate.py
+++ b/tests/hermes_cli/test_plugin_validate.py
@@ -344,6 +344,24 @@ class TestDesktopSurface:
assert "dynamic import outside the SDK (desktop/plugin.js:3)" in failed["desktop surface"]
assert ":4)" not in failed["desktop surface"]
+ def test_bundled_library_own_class_prototypes_pass_but_renderer_globals_still_fail(self, tmp_path):
+ """A bundled library setting fields on classes it declares (three.js: ``var Vector2 = class
+ _Vector2 { constructor() { _Vector2.prototype.isVector2 = true } }``, ``function Track(){}``)
+ is not prototype patching. A write to a renderer global or an undeclared receiver still is,
+ including a global the file shadows with a same-named class elsewhere."""
+ d = self._desktop_plugin(tmp_path, (
+ "var Vector2 = class _Vector2 { constructor() { _Vector2.prototype.isVector2 = true } }\n"
+ "function Track() {}\nTrack.prototype.ValueTypeName = 'vector'\n"
+ "const S = window.Storage\nS.prototype.setItem = noop\n"
+ "class Storage {}\nStorage.prototype.setItem = noop\n"
+ "HTMLElement.prototype.click = spy\n"
+ ))
+ assert desktop_surface_hits(d) == [
+ "prototype patching (desktop/plugin.js:5)",
+ "prototype patching (desktop/plugin.js:7)",
+ "prototype patching (desktop/plugin.js:8)",
+ ]
+
def test_node_sidecar_and_test_mjs_outside_desktop_are_not_the_surface(self, tmp_path):
"""A tools plugin with a Node sidecar (``sidecar/*.mjs`` lazily importing a lockfile-pinned
dependency) and ``tests/*.test.mjs`` has no Desktop surface: the lint stays silent, and the
diff --git a/website/docs/developer-guide/plugins/catalog-submission.md b/website/docs/developer-guide/plugins/catalog-submission.md
index 8c3214ab60f..942bea6d4f9 100644
--- a/website/docs/developer-guide/plugins/catalog-submission.md
+++ b/website/docs/developer-guide/plugins/catalog-submission.md
@@ -106,7 +106,9 @@ the gallery. There is no separate listing to maintain.
8. **Desktop plugins stay inside the SDK surface.** A `desktop/plugin.js` runs
in the Desktop renderer with the app's full authority (the loader isolates
errors, not capabilities), so a listed one may only use the plugin SDK:
- no prototype patching (`X.prototype.y =`, `Object.defineProperty(...prototype`),
+ no prototype patching of renderer or browser objects (`Storage.prototype.y =`,
+ `Object.defineProperty(...prototype`); a bundled library setting fields on
+ classes it declares itself (three.js and the like) is fine,
no `eval`/`new Function`, no `import()` of anything but `@hermes/plugin-sdk`
/ `react` (app bundle chunks, blob or http URLs included), no script-tag
injection, no reaching into the app's internal stores or its own markup