plugin_validate_private_imports.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243
  1. """Admission lint: name a plugin's imports of private Hermes core modules (a warning, never a refusal).
  2. Catalog rule 9 ("public surfaces only") is enforced for runtime rebinds by
  3. ``plugin_validate_core_override``; an import of a core internal (``tools.tirith_security``,
  4. ``hermes_cli.cli_config_load._parse_service_tier_config``) passes that check yet breaks the plugin on
  5. the release that moves or removes the internal. This static pass lists those imports, with
  6. file:line, so reviewers see the coupling at admission. Imports of the plugin's own modules, the
  7. standard library and third-party packages are never flagged; neither are ``TYPE_CHECKING`` imports.
  8. """
  9. from __future__ import annotations
  10. import ast
  11. import tomllib
  12. from functools import lru_cache
  13. from pathlib import Path
  14. from hermes_cli.plugin_validate_core_override import _hermes_top_level, _python_files
  15. # WHY: "public" must mean what Hermes documents for plugin authors, not a reviewer's taste.
  16. # Derived from every Hermes-module ``import`` in website/docs/developer-guide/**/*.md and
  17. # website/docs/user-guide/features/plugins*.md code blocks (plus extending-the-dashboard.md, which
  18. # desktop-plugin-sdk.md names as the plugin backend reference), and what PluginContext hands out in
  19. # hermes_cli/plugins.py (property/return types, base classes its ``register_*`` methods check), and
  20. # the names those plugin pages tell authors to call, raise, return or subclass in prose. ``module`` entries allow the module (underscore names excepted);
  21. # ``module:Name`` entries allow one name. Re-harvest when those docs or PluginContext change.
  22. _PUBLIC = frozenset({
  23. # developer-guide / plugins docs
  24. "agent.account_usage", "agent.acp_client", "agent.browser_provider", "agent.context_engine", "agent.credential_pool",
  25. "agent.delegation_backends", "agent.delegation_provider", "hermes_cli.auth_model_picker:prompt_model_selection",
  26. "hermes_cli.auth:resolve_external_process_provider_credentials", "hermes_cli.model_setup",
  27. "agent.image_gen_provider", "agent.memory_manager", "agent.memory_provider", "agent.secret_scope",
  28. "agent.secret_sources.base", "agent.subagent_lifecycle", "agent.terminal_env_provider",
  29. "agent.transports", "agent.transports.chat_completions", "agent.video_gen_provider",
  30. "agent.web_search_provider", "cli", "gateway.config", "gateway.platform_registry",
  31. "gateway.platforms._shared", "gateway.platforms.base", "gateway.platforms.event",
  32. "gateway.platforms.helpers", "gateway.status", "hermes_cli.auth_oauth_pkce_plugin",
  33. "hermes_cli.config", "hermes_cli.plugin_events", "hermes_cli.plugin_provider_requests",
  34. "hermes_constants", "hermes_platform", "hermes_state", "plugins.plugin_storage", "plugins.plugin_utils", "pm",
  35. "providers", "providers.base", "tools.browser_supervisor", "tools.browser_supervisor_capture",
  36. "tools.computer_use.backend", "tools.registry",
  37. # PluginContext (hermes_cli/plugins.py)
  38. "agent.context_references", "agent.plugin_llm", "agent.transcription_provider", "agent.tts_provider",
  39. "cron.execution_identity",
  40. "hermes_cli.dashboard_auth", "hermes_cli.platform_actions", "hermes_cli.plugins:PluginContext",
  41. "hermes_cli.plugins_ledger:PluginRegistration", "hermes_cli.plugins_state:PluginState",
  42. # prose in memory-provider / model-provider / terminal-environment plugin pages
  43. "agent.runtime_cwd:resolve_agent_cwd", "agent.usage_pricing:CostResult", "hermes_cli.auth_constants:AuthError",
  44. "tools.environments.base:BaseEnvironment", "tools.environments:BaseEnvironment", # package ``__all__``
  45. "utils:atomic_json_write", "utils:read_json_or_empty",
  46. # adding-platform-adapters.md § Public helpers for platform plugins
  47. "gateway.platforms.access_policy_mixin:OwnAccessPolicyMixin", "tools.approval:resolve_gateway_approval",
  48. "tools.approval:resolve_gateway_approval_card",
  49. "tools.clarify_gateway:get_pending", "tools.clarify_gateway:resolve_gateway_clarify",
  50. "tools.clarify_gateway:mark_awaiting_text", "tools.clarify_gateway:SKIPPED",
  51. "tools.url_safety:is_safe_url", "tools.url_safety:create_ssrf_safe_async_client",
  52. "gateway.platforms._http_client_limits:platform_httpx_limits",
  53. "hermes_cli.gateway_setup_wizard:print_setup_header", "hermes_cli.gateway_setup_wizard:confirm_reconfigure",
  54. "hermes_cli.gateway_setup_wizard:offer_home_channel", "hermes_cli.gateway_setup_wizard:save_env_values",
  55. "hermes_cli.gateway_setup_wizard:prompt_csv", "hermes_cli.setup:prompt", "hermes_cli.setup:prompt_choice",
  56. "hermes_cli.setup:prompt_yes_no", "hermes_cli.cli_output",
  57. # plugins/index.md § Read the skill catalog
  58. "tools.skills_tool:find_all_skills", "tools.skills_tool:sort_skills", "tools.skills_tool:skill_search_dirs",
  59. "tools.skills_tool:locate_skill", "tools.skills_tool:skill_lookup_path_error",
  60. "tools.skills_sync:dir_hash", "tools.skill_usage:read_skill_name",
  61. # plugins/index.md § platform plugins: read session identity through the task-local context
  62. "gateway.session_context:get_session_env",
  63. })
  64. _SHOWN = 10
  65. @lru_cache(maxsize=1)
  66. def _hermes_packages() -> frozenset:
  67. """Hermes-owned top-level names: pyproject's ``packages.find`` includes plus the root modules
  68. setup.py ships as ``py-modules`` (every root ``*.py``)."""
  69. root = Path(__file__).resolve().parents[1]
  70. try:
  71. pyproject = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8-sig"))
  72. packages = {name.split(".")[0] for name in pyproject["tool"]["setuptools"]["packages"]["find"]["include"]}
  73. except (OSError, KeyError, ValueError):
  74. packages = set(_hermes_top_level()) - {"hermes_plugins", "tests", "evals"}
  75. return frozenset((packages | {p.stem for p in root.glob("*.py")}) - {"setup", "conftest"})
  76. def _local_modules(rels) -> set[str]:
  77. """Every dotted name under which one of the plugin's own files could be imported."""
  78. names = set()
  79. for rel in rels:
  80. parts = rel.with_suffix("").parts
  81. parts = parts[:-1] if parts[-1] == "__init__" else parts
  82. names |= {".".join(parts[start:end]) for start in range(len(parts)) for end in range(start + 1, len(parts) + 1)}
  83. return names
  84. def _type_checking_nodes(tree: ast.AST) -> set[int]:
  85. skipped: set[int] = set()
  86. for node in ast.walk(tree):
  87. test = getattr(node, "test", None)
  88. if isinstance(node, ast.If) and (getattr(test, "id", None) or getattr(test, "attr", None)) == "TYPE_CHECKING":
  89. skipped |= {id(n) for stmt in node.body for n in ast.walk(stmt)}
  90. return skipped
  91. def _imported(node: ast.AST) -> list[tuple[str, str]]:
  92. """``(module, name)`` pairs an import node binds; ``name`` is "" for ``import module``."""
  93. if isinstance(node, ast.Import):
  94. return [(alias.name, "") for alias in node.names]
  95. if isinstance(node, ast.ImportFrom) and not node.level and node.module:
  96. return [(node.module, alias.name) for alias in node.names]
  97. if isinstance(node, ast.Call) and node.args and isinstance(node.args[0], ast.Constant) \
  98. and isinstance(node.args[0].value, str) and ast.unparse(node.func) in ("importlib.import_module", "import_module"):
  99. return [(node.args[0].value, "")]
  100. return []
  101. @lru_cache(maxsize=512)
  102. def _core_module_exists(module: str) -> bool:
  103. path = Path(__file__).resolve().parents[1].joinpath(*module.split("."))
  104. return path.with_suffix(".py").is_file() or path.is_dir()
  105. def _is_own_module_path(module: str, local: set[str]) -> bool:
  106. """A Hermes-shaped path that core does not ship but whose tail is one of the plugin's own modules:
  107. the fallback spelling of the plugin's install location (``plugins.memory.openltm._db`` beside
  108. ``from . import _db``). A path core DOES ship stays a core import."""
  109. parts = module.split(".")
  110. return any(".".join(parts[i:]) in local for i in range(1, len(parts))) and not _core_module_exists(module)
  111. def _private_target(module: str, name: str, core: frozenset, local: set[str]) -> str:
  112. """The dotted target to report, or "" when the import is public, local or not Hermes's."""
  113. target = f"{module}.{name}" if name else module
  114. own = _is_own_module_path(module, local) or bool(name) and _is_own_module_path(target, local)
  115. hermes = module.split(".")[0] in core and module not in local and not own
  116. public = target in _PUBLIC or f"{module}:{name}" in _PUBLIC \
  117. or (module in _PUBLIC and not name.startswith("_")) # ``from gateway.platforms import base`` too
  118. return target if hermes and not public else ""
  119. def _parsed_files(plugin_dir: Path) -> list[tuple[Path, ast.AST]]:
  120. """``(rel, tree)`` for every plugin module that can load inside Hermes. Hidden dirs (``.github/``
  121. CI helpers) never do; tests and vendored envs are skipped by ``_python_files``."""
  122. parsed = []
  123. for path, rel in _python_files(plugin_dir):
  124. if any(p.startswith(".") for p in rel.parts[:-1]):
  125. continue
  126. try:
  127. parsed.append((rel, ast.parse(path.read_text(encoding="utf-8-sig", errors="replace"))))
  128. except (SyntaxError, ValueError):
  129. continue
  130. return parsed
  131. def private_import_findings(plugin_dir: Path) -> list[str]:
  132. """``["<rel>:<line> <module>[.<name>]", ...]`` for every import of a private Hermes core module:
  133. the first site of each distinct module first (so a truncated list still shows the breadth),
  134. then the rest, each group in file/line order."""
  135. files = _parsed_files(Path(plugin_dir))
  136. local = _local_modules(rel for rel, _tree in files)
  137. core = _hermes_packages()
  138. found: set[tuple[str, int, str, str]] = set()
  139. for rel, tree in files:
  140. skipped = _type_checking_nodes(tree)
  141. for node in ast.walk(tree):
  142. if id(node) in skipped:
  143. continue
  144. for module, name in _imported(node):
  145. target = _private_target(module, name, core, local)
  146. if target:
  147. found.add((rel.as_posix(), getattr(node, "lineno", 0), target, module))
  148. seen: set[str] = set()
  149. first = [site for site in sorted(found) if site[3] not in seen and not seen.add(site[3])]
  150. rest = sorted(found.difference(first))
  151. return [f"{rel}:{line} {target}" for rel, line, target, _module in first + rest]
  152. # The core objects a plugin holds a live handle to — ``SessionDB`` (``ctx`` session APIs, the
  153. # dashboard), ``AIAgent`` and ``GatewayRunner`` (hook kwargs), ``PluginContext`` — split across their
  154. # facade + sibling files. Calling one of their private methods (``db._execute_write(...)``,
  155. # ``runner._evict_cached_agent(...)``) couples the plugin to core internals exactly like a private
  156. # import, but no import names it, so the import pass above cannot see it.
  157. _CORE_HANDLE_SOURCES = ("hermes_state.py", "hermes_state_*.py", "run_agent.py", "agent/turn_*.py",
  158. "gateway/run.py", "gateway/run_*.py", "hermes_cli/plugins.py")
  159. @lru_cache(maxsize=1)
  160. def _core_private_methods() -> frozenset:
  161. root = Path(__file__).resolve().parents[1]
  162. names: set[str] = set()
  163. for pattern in _CORE_HANDLE_SOURCES:
  164. for path in root.glob(pattern):
  165. try:
  166. tree = ast.parse(path.read_text(encoding="utf-8-sig"))
  167. except (OSError, SyntaxError, ValueError):
  168. continue
  169. names |= {item.name for node in ast.walk(tree) if isinstance(node, ast.ClassDef) for item in node.body
  170. if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef))
  171. and item.name.startswith("_") and not item.name.startswith("__")}
  172. return frozenset(names)
  173. def _own_names(files: list[tuple[Path, ast.AST]]) -> set[str]:
  174. """Every name the plugin defines or assigns, so its own ``obj._helper()`` never reads as core."""
  175. own: set[str] = set()
  176. for _rel, tree in files:
  177. for node in ast.walk(tree):
  178. if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
  179. own.add(node.name)
  180. elif isinstance(node, ast.Attribute) and isinstance(node.ctx, ast.Store):
  181. own.add(node.attr)
  182. elif isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
  183. own.add(node.id)
  184. return own
  185. def private_attribute_findings(plugin_dir: Path) -> list[str]:
  186. """``["<rel>:<line> <expr>", ...]`` for every access to a private method of a core handle class
  187. that the plugin does not define itself (``self``/``cls`` receivers excluded)."""
  188. files = _parsed_files(Path(plugin_dir))
  189. private = _core_private_methods() - _own_names(files)
  190. found = {(rel.as_posix(), node.lineno, ast.unparse(node)[:80]) for rel, tree in files for node in ast.walk(tree)
  191. if isinstance(node, ast.Attribute) and node.attr in private
  192. and not (isinstance(node.value, ast.Name) and node.value.id in ("self", "cls"))}
  193. return [f"{rel}:{line} {expr}" for rel, line, expr in sorted(found)]
  194. def _warn_sites(report, label: str, hits: list[str]) -> None:
  195. more = f"; and {len(hits) - _SHOWN} more" if len(hits) > _SHOWN else ""
  196. report.warn(
  197. f"{label} (catalog rule 9: public surfaces only; these can break on any release): "
  198. + "; ".join(hits[:_SHOWN]) + more
  199. + ". Use ctx.* / documented plugin APIs, or open an issue for the seam you need."
  200. )
  201. def check_private_imports(report, plugin_dir: Path) -> None:
  202. """Warn (never fail) when the plugin imports private Hermes core modules or calls private
  203. methods on the core objects it is handed."""
  204. if hits := private_import_findings(plugin_dir):
  205. _warn_sites(report, "private core imports", hits)
  206. if hits := private_attribute_findings(plugin_dir):
  207. _warn_sites(report, "private core attribute access", hits)