Files
hermes-agent/scripts/install_root_lint.py
alt-glitch 97dbdb3890 fix(install-root-lint): count a climb once, not once per shorter climb inside it
A fixed three-level climb in a moved file also matched as its inner two-level climb, which the
moved-file check read as a stale root climb (hermes_agent/hermes_cli/linux_desktop_entry.py:523 on
chunk 11).
2026-11-13 20:47:04 +00:00

218 lines
11 KiB
Python
Executable File

#!/usr/bin/env python3
"""Ratchet lint for hand-written install-root paths in production code.
* **root_from_file**: a ``__file__`` path expression that climbs to the install root
(``Path(__file__).resolve().parents[1]`` in ``hermes_cli/x.py``, ``os.path.dirname(__file__)`` in a
root module). The climb counts ``.parent``, ``.parents[n]``, ``os.path.dirname`` and
``os.path.join(..., os.pardir)``; it reaches the root when it climbs as many levels as the file is
deep. ``hermes_cli._startup_fast.project_root_str()`` owns that answer.
* **module_sys_path**: a ``sys.path`` edit that runs when the module is imported (module level, outside
functions and the ``if __name__ == "__main__"`` block).
Production code is pyproject's ``packages.find`` packages and the root ``*.py`` modules. Not caught: a
climb through a variable (``_pkg = Path(__file__).parent`` then ``_pkg.parent``).
Existing sites never fail anything. ``scripts/install_root_lint_baseline.json`` counts them per kind
and file, and its ``reasons`` map says why each file cannot call the owner; the lint fails only when a
file's count rises above it. Run ``--update`` after removing a
site, or to record an intended one.
"""
from __future__ import annotations
import argparse
import ast
import json
import sys
import tomllib
from collections import Counter
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
sys.path.append(str(ROOT))
from hermes_agent.compat.paths import current_path, original_path
BASELINE = ROOT / "scripts" / "install_root_lint_baseline.json"
KINDS = ("root_from_file", "module_sys_path")
# A climb in a moved file that reached the root at the file's old depth now stops inside the package.
MOVED = "moved_climb"
# The owner looks for the folder that holds hermes_agent/, so its climb is right at either depth.
OWNER = "hermes_cli/_startup_fast.py"
FIX_HINT = ("Call hermes_cli._startup_fast.project_root_str() for the install root, and leave sys.path to"
" the entry point. If the site is intended, run `python scripts/install_root_lint.py --update`"
" and say why in the PR.")
_SKIP_PARTS = {"tests", "__pycache__", "node_modules"}
# Files scripts/move/generate_shims.py writes at old module paths (shims and copies) are listed in
# this .gitattributes block; their root math is generated.
_GENERATED_BLOCK = ("# BEGIN shims (generated by scripts/move/generate_shims.py; do not edit)\n", "# END shims\n")
_SAME_LEVEL = {"abspath", "realpath", "normpath", "resolve", "absolute", "Path", "PurePath", "str", "fspath"}
def production_files(root: Path = ROOT) -> list[Path]:
"""Repo-relative paths of the shipped packages' and root modules' Python files."""
find = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8-sig"))
tops = {name.split(".")[0] for name in find["tool"]["setuptools"]["packages"]["find"]["include"]}
files = [p for top in tops for p in (root / top).rglob("*.py")]
files += [p for p in root.glob("*.py") if p.stem not in {"setup", "conftest"}]
rels = {p.relative_to(root) for p in files}
return sorted(rel for rel in rels if not _SKIP_PARTS.intersection(rel.parts[:-1]))
def _name(node: ast.AST) -> str:
"""The last dotted component a call names (``os.path.dirname`` -> ``dirname``)."""
return node.attr if isinstance(node, ast.Attribute) else node.id if isinstance(node, ast.Name) else ""
def _is_pardir(node: ast.AST) -> bool:
return _name(node) == "pardir" or (isinstance(node, ast.Constant) and node.value == "..")
def climb(node: ast.AST) -> int | None:
"""Directory levels above the file that ``node`` names, or None when it is not ``__file__`` math."""
if isinstance(node, ast.Name):
return 0 if node.id == "__file__" else None
if isinstance(node, ast.Attribute) and node.attr == "parent":
base = climb(node.value)
return None if base is None else base + 1
if (isinstance(node, ast.Subscript) and isinstance(node.value, ast.Attribute) and node.value.attr == "parents"
and isinstance(node.slice, ast.Constant) and isinstance(node.slice.value, int)):
base = climb(node.value.value)
return None if base is None else base + node.slice.value + 1
if not isinstance(node, ast.Call):
return None
name = _name(node.func)
if name in {"resolve", "absolute"} and isinstance(node.func, ast.Attribute) and not node.args:
return climb(node.func.value)
if not node.args or isinstance(node.args[0], ast.Starred):
return None
base = climb(node.args[0])
if base is None:
return None
if name in _SAME_LEVEL and len(node.args) == 1:
return base
if name == "dirname" and len(node.args) == 1:
return base + 1
if name == "join" and all(_is_pardir(arg) for arg in node.args[1:]):
return base + len(node.args) - 1
return None
def _script_only_branches(test: ast.expr) -> tuple[str, str] | None:
"""For ``__name__ == "__main__"`` / ``!=``: which If branch runs only as a script, and which at import."""
if (isinstance(test, ast.Compare) and len(test.ops) == 1 and len(test.comparators) == 1
and {ast.unparse(test.left), ast.unparse(test.comparators[0])} == {"__name__", "'__main__'"}):
if isinstance(test.ops[0], ast.Eq):
return "body", "orelse"
if isinstance(test.ops[0], ast.NotEq):
return "orelse", "body"
return None
def _module_level(body: list[ast.stmt]):
"""Statements that run at import: into if/try/with/loops/match and class bodies, not into defs or a
script-only ``__main__`` branch."""
for stmt in body:
if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
continue
if isinstance(stmt, ast.If) and (branches := _script_only_branches(stmt.test)) is not None:
yield from _module_level(getattr(stmt, branches[1]))
continue
yield stmt
for field in ("body", "orelse", "finalbody", "handlers"):
yield from _module_level(getattr(stmt, field, []))
for case in getattr(stmt, "cases", []):
yield from _module_level(case.body)
_SYS_PATH_METHODS = {f"sys.path.{m}" for m in ("insert", "append", "extend", "remove", "pop", "clear")}
def _edits_sys_path(stmt: ast.stmt) -> bool:
"""A ``sys.path`` list method call, ``del`` of it or a slice, or an assignment to it or a slice."""
if isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Call):
return ast.unparse(stmt.value.func) in _SYS_PATH_METHODS
if isinstance(stmt, ast.Delete):
targets = stmt.targets
else:
targets = stmt.targets if isinstance(stmt, ast.Assign) else [getattr(stmt, "target", None)]
return any(target is not None and ast.unparse(target).split("[")[0] == "sys.path" for target in targets)
def _generated_files(root: Path) -> set[str]:
"""Repo-relative paths in the generated-shims block of ``.gitattributes``."""
attributes = root / ".gitattributes"
text = attributes.read_text(encoding="utf-8-sig") if attributes.is_file() else ""
block = text.partition(_GENERATED_BLOCK[0])[2].partition(_GENERATED_BLOCK[1])[0]
return {line.split()[0].removeprefix("/") for line in block.splitlines() if line.strip()}
def collect(root: Path = ROOT) -> dict[str, list[str]]:
"""Per kind and ``MOVED``, ``["<rel>:<line>", ...]``. A climb reaches the root by the file's current depth."""
found: dict[str, set[tuple[str, int]]] = {kind: set() for kind in (*KINDS, MOVED)}
generated = _generated_files(root)
for rel in production_files(root):
if rel.as_posix() in generated:
continue
text = (root / rel).read_text(encoding="utf-8-sig")
tree = ast.parse(text)
old_depth = len(original_path(rel.as_posix()).split("/"))
inner: set[int] = set() # the shorter climbs inside a longer one are not sites of their own
for node in ast.walk(tree):
if id(node) in inner or not isinstance(node, ast.expr) or (levels := climb(node)) is None:
continue
inner.update(id(sub) for sub in ast.walk(node) if sub is not node)
if levels >= len(rel.parts):
found["root_from_file"].add((rel.as_posix(), node.lineno))
elif old_depth < len(rel.parts) and levels >= old_depth:
found[MOVED].add((rel.as_posix(), node.lineno))
for stmt in _module_level(tree.body):
if _edits_sys_path(stmt):
found["module_sys_path"].add((rel.as_posix(), stmt.lineno))
return {kind: [f"{rel}:{line}" for rel, line in sorted(sites)] for kind, sites in found.items()}
def tally(found: dict[str, list[str]]) -> dict[str, dict[str, int]]:
return {kind: dict(sorted(Counter(original_path(site.rsplit(":", 1)[0]) for site in found[kind]).items())) for kind in KINDS}
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]:
return [f"{kind}: {current_path(rel)} ({n}, baseline {baseline.get(kind, {}).get(rel, 0)})" for kind in KINDS
for rel, n in current[kind].items() if n > baseline.get(kind, {}).get(rel, 0)]
def moved_climbs(found: dict[str, list[str]], baseline: dict[str, dict[str, int]]) -> list[str]:
"""Climbs in moved files the baseline knew as root climbs, that no longer reach the root. A new file
in a moved package climbing to the package is not one: only baselined files climbed to the root."""
known = set(baseline.get("root_from_file", {})) - {OWNER}
return [site for site in found[MOVED] if original_path(site.rsplit(":", 1)[0]) in known]
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=(__doc__ or "").split("\n\n")[0])
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)
if stale := moved_climbs(found, read_baseline()):
print("moved files whose install-root climb now stops inside hermes_agent/:\n " + "\n ".join(stale)
+ f"\n{FIX_HINT}", file=sys.stderr)
return 1
if args.update:
reasons = {rel: why for rel, why in read_baseline().get("reasons", {}).items()
if any(rel in current[kind] for kind in KINDS)}
BASELINE.write_text(json.dumps({**current, "reasons": reasons}, indent=2) + "\n", encoding="utf-8")
print(f"wrote {BASELINE.relative_to(ROOT)}")
return 0
if rises := regressions(current, read_baseline()):
print("new install-root sites:\n " + "\n ".join(rises) + f"\n{FIX_HINT}", file=sys.stderr)
return 1
print(", ".join(f"{kind}: {sum(current[kind].values())}" for kind in KINDS))
return 0
if __name__ == "__main__":
raise SystemExit(main())