mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-20 18:50:12 +03:00
f7714339bc
boundary_lint, check_agents_md_size and the old-updater audit take a root that can be a fixture or another checkout; they map paths through that tree's moves.py. resolve_in_tree reads a moved module where it lives, not the forwarder at its old path (scouts 07, 08 and 12 each carried a copy of this). boundary-lint reports targets under their original name, as its baseline keys them.
197 lines
9.1 KiB
Python
Executable File
197 lines
9.1 KiB
Python
Executable File
#!/usr/bin/env -S bash -c 'exec "$BASH" "$(dirname "$0")/run-in-hermes-env" python3 "$0" "$@"'
|
|
"""Report-only import lint for the core/module boundary, in both directions.
|
|
|
|
* **module -> core internals**: a bundled module imports a Hermes module or name that is not on the
|
|
published plugin API (``hermes_cli/data/plugin_api.json``), e.g. ``gateway.run``. The rule is the one
|
|
``hermes plugins validate`` warns with (``plugin_validate_private_imports.private_import_findings``),
|
|
so the lint and the plugin-author warning cannot drift.
|
|
* **core -> module**: core code imports a specific module (``plugins.platforms.discord.adapter``)
|
|
instead of reaching it through discovery and the plugin contracts.
|
|
|
|
A *module* is a directory under ``plugins/`` with a ``plugin.yaml`` manifest, or a ``plugins/<name>/``
|
|
with a ``dashboard/manifest.json``. Everything else under ``plugins/`` (``plugin_loader``,
|
|
``plugin_utils``, ``plugins/memory/__init__.py`` discovery, ...) is core plugin plumbing. *Core* is
|
|
every other file of the shipped packages (pyproject ``packages.find``) and the root ``*.py`` modules;
|
|
tests, scripts, docs and skills are neither.
|
|
|
|
Existing violations never fail anything. ``scripts/boundary_lint_baseline.json`` counts each crossing
|
|
by importing file and target (``<file> <target>``); ``--check`` (and
|
|
``tests/scripts/test_boundary_lint.py``) fails only when a crossing's count rises above it, and names
|
|
that crossing. Run ``--update`` to record an intended import, or to drop the entries a change removed.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import ast
|
|
import json
|
|
import sys
|
|
from collections import Counter
|
|
from pathlib import Path
|
|
from typing import NoReturn
|
|
|
|
ROOT = Path(__file__).resolve().parent.parent
|
|
BASELINE = ROOT / "scripts" / "boundary_lint_baseline.json"
|
|
DIRECTIONS = ("module_to_core", "core_to_module")
|
|
FIX_HINT = ("Import the published plugin API (hermes_cli/data/plugin_api.json) or reach the module through"
|
|
" discovery; if the import is intended, run `python scripts/boundary_lint.py --update` and say why"
|
|
" in the PR.")
|
|
_SKIP_PARTS = {"tests", "__pycache__", "node_modules", "dist", ".venv", "venv"}
|
|
|
|
if str(ROOT) not in sys.path:
|
|
sys.path.insert(0, str(ROOT))
|
|
|
|
from hermes_agent.compat.paths import original_module, original_path, tree_moves
|
|
from hermes_cli.plugin_validate_private_imports import (
|
|
_hermes_packages,
|
|
_imported,
|
|
_type_checking_nodes,
|
|
private_import_findings,
|
|
)
|
|
|
|
|
|
def _nothing_to_scan(what: str) -> NoReturn:
|
|
print(f"{what}: a scan root that moved would be skipped in silence", file=sys.stderr)
|
|
raise SystemExit(2)
|
|
|
|
|
|
def module_dirs(root: Path = ROOT) -> list[Path]:
|
|
"""Every bundled module directory under ``plugins/``."""
|
|
plugins = root / tree_moves(root).current("plugins")
|
|
if not plugins.is_dir():
|
|
_nothing_to_scan(f"{plugins} does not exist")
|
|
dirs = {p.parent for p in plugins.rglob("plugin.yaml") if not _SKIP_PARTS.intersection(p.relative_to(plugins).parts)}
|
|
dirs |= {p.parent.parent for p in plugins.glob("*/dashboard/manifest.json")}
|
|
return sorted(dirs)
|
|
|
|
|
|
def module_to_core(root: Path = ROOT) -> list[str]:
|
|
"""``["plugins/<module>/<rel>:<line> <target>", ...]`` for every module import of a core internal.
|
|
An in-tree module's full-path import of itself (``plugins.web.exa.provider``) or of another module
|
|
is not a core import, so it is left out."""
|
|
modules = module_dirs(root)
|
|
hits = [(d, *hit.split(" ", 1)) for d in modules for hit in private_import_findings(d)]
|
|
return [f"{d.relative_to(root).as_posix()}/{loc} {original_module(target)}" for d, loc, target in hits
|
|
if not _in_module(target, root, modules)]
|
|
|
|
|
|
def _core_files(root: Path, modules: list[Path]):
|
|
seen: set[Path] = set()
|
|
for top in sorted(_hermes_packages()):
|
|
package = root / tree_moves(root).current(top)
|
|
paths = sorted(package.rglob("*.py")) if package.is_dir() else [root / tree_moves(root).current(f"{top}.py")]
|
|
for path in paths:
|
|
rel = path.relative_to(root)
|
|
if path in seen or not path.is_file():
|
|
continue
|
|
seen.add(path)
|
|
if _SKIP_PARTS.intersection(rel.parts[:-1]) or path.name.startswith("test_"):
|
|
continue
|
|
if any(path.is_relative_to(d) for d in modules):
|
|
continue
|
|
yield path, rel
|
|
if not seen:
|
|
_nothing_to_scan(f"no core file under {root}")
|
|
|
|
|
|
def _absolute(rel: Path, node: ast.ImportFrom) -> str:
|
|
"""The dotted module a relative ``from . import x`` in ``rel`` names."""
|
|
package = list(rel.with_suffix("").parts[:-1])
|
|
base = package[: len(package) - (node.level - 1)] if node.level > 1 else package
|
|
return ".".join(base + ([node.module] if node.module else []))
|
|
|
|
|
|
def _targets(rel: Path, node: ast.AST) -> list[list[str]]:
|
|
"""Per imported alias, the dotted spellings it could name (``pkg.name`` and ``pkg`` for a from-import)."""
|
|
if isinstance(node, ast.ImportFrom) and node.level:
|
|
module = _absolute(rel, node)
|
|
return [[f"{module}.{alias.name}", module] for alias in node.names]
|
|
return [[f"{m}.{n}", m] if n else [m] for m, n in _imported(node)]
|
|
|
|
|
|
def _in_module(target: str, root: Path, modules: list[Path]) -> bool:
|
|
"""Whether the dotted ``target`` (a module, or a name in one) is a file or package inside a module."""
|
|
parts = original_module(target).split(".")
|
|
if parts[0] != "plugins":
|
|
return False
|
|
for end in range(len(parts), 1, -1):
|
|
path = root / tree_moves(root).current("/".join(parts[:end]))
|
|
for candidate in (path, path.with_suffix(".py")):
|
|
if candidate.exists():
|
|
return any(candidate.is_relative_to(d) for d in modules)
|
|
return False
|
|
|
|
|
|
def core_to_module(root: Path = ROOT) -> list[str]:
|
|
"""``["<rel>:<line> <module path>", ...]`` for every core import that names a specific module."""
|
|
modules = module_dirs(root)
|
|
found: set[tuple[str, int, str]] = set()
|
|
for path, rel in _core_files(root, modules):
|
|
try:
|
|
tree = ast.parse(path.read_text(encoding="utf-8-sig"))
|
|
except (OSError, SyntaxError, ValueError):
|
|
continue
|
|
skipped = _type_checking_nodes(tree)
|
|
for node in ast.walk(tree):
|
|
if id(node) in skipped:
|
|
continue
|
|
for spellings in _targets(rel, node):
|
|
# Collapse the spellings of one alias to one target; distinct aliases count separately.
|
|
if hits := [t for t in spellings if _in_module(t, root, modules)]:
|
|
found.add((rel.as_posix(), getattr(node, "lineno", 0), min(hits, key=len)))
|
|
return [f"{rel}:{line} {original_module(target)}" for rel, line, target in sorted(found)]
|
|
|
|
|
|
def collect(root: Path = ROOT) -> dict[str, list[str]]:
|
|
return {"module_to_core": module_to_core(root), "core_to_module": core_to_module(root)}
|
|
|
|
|
|
def _key(site: str) -> str:
|
|
"""What a site couples: ``<importing file> <target>`` (repo-relative path, line dropped). Two
|
|
branches that add the same target from different files add two different keys; a file that imports
|
|
one target twice counts 2 under one key."""
|
|
loc, target = site.split(" ", 1)
|
|
return f"{original_path(loc.rsplit(':', 1)[0])} {original_module(target)}"
|
|
|
|
|
|
def tally(found: dict[str, list[str]]) -> dict[str, dict[str, int]]:
|
|
"""Per direction, ``{key: count}`` with the keys of ``_key``."""
|
|
return {d: dict(sorted(Counter(_key(site) for site in found[d]).items())) for d in DIRECTIONS}
|
|
|
|
|
|
def read_baseline(path: Path = BASELINE) -> dict[str, dict[str, int]]:
|
|
return json.loads(path.read_text(encoding="utf-8-sig"))
|
|
|
|
|
|
def regressions(current: dict[str, dict[str, int]], baseline: dict[str, dict[str, int]]) -> list[str]:
|
|
"""One line per key whose count rose above the baseline: a swap still fails, and the line names
|
|
the new import."""
|
|
return [f"{d}: {key} ({n}, baseline {baseline.get(d, {}).get(key, 0)})" for d in DIRECTIONS
|
|
for key, n in current[d].items() if n > baseline.get(d, {}).get(key, 0)]
|
|
|
|
|
|
def main(argv: list[str] | None = None) -> int:
|
|
parser = argparse.ArgumentParser(description=(__doc__ or "").split("\n\n")[0])
|
|
parser.add_argument("--list", action="store_true", help="print every violation site")
|
|
parser.add_argument("--check", action="store_true", help="exit 1 when a count rises above the baseline")
|
|
parser.add_argument("--update", action="store_true", help="rewrite the baseline with the current sites")
|
|
args = parser.parse_args(argv)
|
|
found = collect()
|
|
current = tally(found)
|
|
for direction in DIRECTIONS:
|
|
print(f"{direction}: {len(found[direction])}")
|
|
if args.list:
|
|
print("".join(f" {site}\n" for site in found[direction]), end="")
|
|
if args.update:
|
|
BASELINE.write_text(json.dumps(current, indent=2) + "\n", encoding="utf-8")
|
|
print(f"wrote {BASELINE.relative_to(ROOT)}")
|
|
return 0
|
|
if args.check and (rises := regressions(current, read_baseline())):
|
|
print("new boundary imports:\n " + "\n ".join(rises) + f"\n{FIX_HINT}", file=sys.stderr)
|
|
return 1
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|