henxels 0.3.0__py3-none-any.whl

henxels/__init__.py

@@ -0,0 +1,17 @@
+"""henxels — external structure that gives shape to your project.
+
+Custom checks register with the ``@statement`` decorator:
+
+    from henxels import statement
+
+    @statement("max_lines")
+    def max_lines(limit, scope):
+        return [f"{f} is too long" for f in scope.files
+                if scope.line_count(f) > limit]
+"""
+
+from henxels.statements import Scope, as_list, statement
+
+__version__ = "0.2.0"
+
+__all__ = ["statement", "Scope", "as_list", "__version__"]

henxels/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m henxels`` (used as a hook fallback when the script isn't on PATH)."""
+
+import sys
+
+from henxels.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

henxels/bless.py

@@ -0,0 +1,68 @@
+"""Conscious-override tokens — the elegant escape hatch for guards.
+
+A guard blocks a destructive reflex (push, deleting lines/files). To proceed you run
+a deliberate, non-standard verb — ``henxels bless push`` — which mints a one-time
+token. The git hook then *consumes* it. A reflexive retry can't reuse the token
+because it's bound to a fingerprint (the exact SHA being pushed, or the exact set of
+deletions) and expires quickly.
+
+Tokens live under ``.git/henxels/`` so they're repo-local and never committed.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+DEFAULT_TTL = 600  # seconds — a bless is a *recent* conscious act, not a standing grant
+
+
+def _store_dir(root: Path | str) -> Path:
+    return Path(root) / ".git" / "henxels"
+
+
+def _token_path(root: Path | str, action: str) -> Path:
+    return _store_dir(root) / f"bless-{action}.json"
+
+
+def bless(root: Path | str, action: str, fingerprint: str, ttl: int = DEFAULT_TTL, now: float | None = None) -> Path:
+    """Mint a one-time token for ``action`` bound to ``fingerprint``."""
+    now = time.time() if now is None else now
+    store = _store_dir(root)
+    store.mkdir(parents=True, exist_ok=True)
+    path = _token_path(root, action)
+    path.write_text(
+        json.dumps({"fingerprint": fingerprint, "expires_at": now + ttl}),
+        encoding="utf-8",
+    )
+    return path
+
+
+def is_blessed(root: Path | str, action: str, fingerprint: str, now: float | None = None) -> bool:
+    """True if a matching, unexpired token exists (without consuming it)."""
+    now = time.time() if now is None else now
+    path = _token_path(root, action)
+    if not path.is_file():
+        return False
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (ValueError, OSError):
+        return False
+    if data.get("fingerprint") != fingerprint:
+        return False
+    if float(data.get("expires_at", 0)) < now:
+        return False
+    return True
+
+
+def consume(root: Path | str, action: str, fingerprint: str, now: float | None = None) -> bool:
+    """Verify a matching token and delete it. Returns True if it was valid."""
+    ok = is_blessed(root, action, fingerprint, now=now)
+    # Always clear the token file: a used token is spent, a stale/mismatched one is junk.
+    _token_path(root, action).unlink(missing_ok=True)
+    return ok
+
+
+def clear(root: Path | str, action: str) -> None:
+    _token_path(root, action).unlink(missing_ok=True)

henxels/casing.py

@@ -0,0 +1,30 @@
+"""Naming conventions — the closed set used by the `casing` statement and Scope."""
+
+from __future__ import annotations
+
+import re
+
+# Keys are the values accepted by the `casing:` statement (and the schema enum).
+# snake_case / SCREAMING_SNAKE_CASE permit leading underscores — `_private.py` and
+# `_helpers.py` are idiomatic Python, not naming violations. (Dunder files like
+# __init__.py are exempted separately, in is_dunder.)
+NAMING_CONVENTIONS: dict[str, str] = {
+    "snake_case": r"^_*[a-z0-9]+(_[a-z0-9]+)*$",
+    "kebab-case": r"^[a-z0-9]+(-[a-z0-9]+)*$",
+    "camelCase": r"^[a-z][a-zA-Z0-9]*$",
+    "PascalCase": r"^[A-Z][a-zA-Z0-9]*$",
+    "SCREAMING_SNAKE_CASE": r"^_*[A-Z0-9]+(_[A-Z0-9]+)*$",
+    "any": r".*",
+}
+
+
+def is_dunder(base: str) -> bool:
+    """Dunder files (__init__, __main__) are language-mandated, not style choices."""
+    return len(base) > 4 and base.startswith("__") and base.endswith("__")
+
+
+def matches(base: str, convention: str) -> bool:
+    pattern = NAMING_CONVENTIONS.get(convention)
+    if pattern is None:
+        return True
+    return not base or is_dunder(base) or bool(re.match(pattern, base))

henxels/catalogue.py

@@ -0,0 +1,128 @@
+"""Discoverability + contribution: browse statements, scaffold new ones, upstream them.
+
+The framework grows by contribution, so reuse must be easy (`catalogue`), authoring
+must be boilerplate-free (`create-new-statement`), and contributing a reusable one
+must be a single nudge (`contribute`).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from henxels.statements.registry import all_statements
+
+LOCAL_CHECK_FILE = "henxels_checks.py"
+
+
+def render_catalogue() -> str:
+    stmts = all_statements()
+    builtin = sorted((d for d in stmts.values() if d.builtin), key=lambda d: d.name)
+    custom = sorted((d for d in stmts.values() if not d.builtin), key=lambda d: d.name)
+
+    lines = ["henxels catalogue — statements you can use inside a henxel", ""]
+    lines.append("Built-in (the standard library):")
+    for d in builtin:
+        lines.append(f"  {d.name:<20} {d.help}{_flags(d)}")
+    if custom:
+        lines += ["", "Custom (loaded from this repo):"]
+        for d in custom:
+            lines.append(f"  {d.name:<20} {d.help or '(no description)'}{_flags(d)}")
+    from henxels.invocation import henxels_cmd
+
+    hx = henxels_cmd()
+    lines += [
+        "",
+        f"Reuse before reinventing. Missing one?  {hx} create-new-statement <name>",
+        f"Reusable beyond this repo?  {hx} contribute  (send a ready-to-merge PR)",
+    ]
+    return "\n".join(lines)
+
+
+def _flags(d) -> str:
+    bits = []
+    if d.per_file:
+        bits.append("per-file")
+    if d.stage:
+        bits.append(d.stage)
+    return f"  [{', '.join(bits)}]" if bits else ""
+
+
+def create_statement_scaffold(name: str, root: Path | str) -> tuple[Path, str]:
+    """Append a template statement to henxels_checks.py. Returns (path, 'created'|'updated')."""
+    root = Path(root)
+    func = _identifier(name)
+    path = root / LOCAL_CHECK_FILE
+    existed = path.is_file()
+    body = "" if existed else "from henxels import statement\n"
+    body += _TEMPLATE.format(name=name, func=func)
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(body)
+    return path, ("updated" if existed else "created")
+
+
+def contribute_guide(name: str | None = None) -> str:
+    lines = [
+        "Contributing a statement upstream (the project thrives on this):",
+        "",
+        "Is it REUSABLE — useful in other repos, not tied to this one's names/paths?",
+        "  • Yes → upstream it as a built-in. Send a ready-to-merge PR (not an issue):",
+        "      1. add the function to henxels/statements/builtins.py with builtin=True",
+        "         and a clear help= string;",
+        "      2. add a test in tests/test_statements.py;",
+        "      3. run the gates locally (lint + tests must pass — PRs arrive merge-ready);",
+        "      4. open the PR at https://github.com/benquemax/henxels",
+        "  • No (ad-hoc to this repo) → keep it local in henxels_checks.py.",
+    ]
+    if name:
+        stmt = all_statements().get(name)
+        if stmt and not stmt.builtin:
+            lines += ["", f"`{name}` is a custom statement — a good contribution candidate."]
+        elif stmt and stmt.builtin:
+            lines += ["", f"`{name}` is already built-in."]
+    return "\n".join(lines)
+
+
+def contribute_snippet(name: str) -> tuple[str, str] | None:
+    """For a local custom statement, return (builtin-ready source, test stub)."""
+    import inspect
+
+    sdef = all_statements().get(name)
+    if not sdef or sdef.builtin:
+        return None
+    try:
+        source = inspect.getsource(sdef.fn).rstrip()
+    except (OSError, TypeError):
+        source = f"# (could not read the source of {name})"
+    func = _identifier(name)
+    test_stub = (
+        f"def test_{func}(tmp_path):\n"
+        f"    # TODO: build a Scope and assert `{name}` returns the right instruction(s)\n"
+        f"    ..."
+    )
+    return source, test_stub
+
+
+def _identifier(name: str) -> str:
+    out = "".join(c if c.isalnum() else "_" for c in name).strip("_")
+    return out or "my_check"
+
+
+_TEMPLATE = '''
+
+@statement("{name}", help="TODO: one-line description")
+def {func}(param, file, scope):
+    """TODO: explain what this checks.
+
+    Args are injected by name — keep only what you need:
+      param     the value from the contract (e.g. 500 for `{name}: 500`)
+      file      asking for `file` makes this PER-FILE (henxels loops for you)
+      scope     scope.files, scope.read_text(f), scope.line_count(f), scope.exists(p)
+
+    Return None/True to pass, or a STRING INSTRUCTION (shown to the agent) to fail.
+
+    Reusable beyond this repo? `henxels contribute {name}`.
+    """
+    # if <something is wrong with `file`>:
+    #     return "do X instead"
+    return None
+'''

henxels/cli.py

@@ -0,0 +1,366 @@
+"""henxels command-line interface (v2).
+
+    henxels init                       scaffold contract + hooks + AGENTS.md digest
+    henxels check [--all|--staged] […] run the contract (every henxel is a test)
+    henxels explain <path>             what governs this location
+    henxels catalogue                  browse the statements you can use
+    henxels create-new-statement <n>   scaffold a local custom statement
+    henxels contribute [name]          how to upstream a reusable statement
+    henxels bless <push|delete>        consciously override a protection
+    henxels sync                       refresh the AGENTS.md digest
+    henxels doctor                     check the setup
+
+Exit codes: 0 = clean, 1 = held by a henxel, 2 = usage/contract problem.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from henxels import settings
+from henxels.contract import (
+    Contract,
+    ContractError,
+    apply_imports,
+    find_contract,
+    load_contract,
+)
+from henxels.diffinfo import staged_diff
+from henxels.engine import gitinfo
+from henxels.engine.discover import discover
+from henxels.engine.report import is_fancy, render, render_summary, summarize
+from henxels.explain import explain_path
+from henxels.findings import Finding
+from henxels.runner import run_contract
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="henxels",
+        description="Suspenders for your repo. Keep your ADHD agent in henxels.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    pi = sub.add_parser("init", help="scaffold the contract, hooks, and AGENTS.md digest")
+    pi.add_argument("--no-hooks", action="store_true")
+    pi.add_argument("--no-digest", action="store_true")
+    pi.add_argument("--force", action="store_true")
+    pi.set_defaults(func=cmd_init)
+
+    pc = sub.add_parser("check", help="run the contract")
+    pc.add_argument("paths", nargs="*")
+    pc.add_argument("--all", action="store_true")
+    pc.add_argument("--staged", action="store_true")
+    pc.add_argument("--config", default=None)
+    pc.add_argument("--plain", action="store_true")
+    pc.set_defaults(func=cmd_check)
+
+    pe = sub.add_parser("explain", help="show the henxels governing a path")
+    pe.add_argument("path")
+    pe.add_argument("--config", default=None)
+    pe.add_argument("--json", action="store_true", help="machine-readable output for agent tooling")
+    pe.set_defaults(func=cmd_explain)
+
+    pcat = sub.add_parser("catalogue", help="browse the statements you can use")
+    pcat.set_defaults(func=cmd_catalogue)
+
+    pn = sub.add_parser("create-new-statement", help="scaffold a custom statement")
+    pn.add_argument("name")
+    pn.set_defaults(func=cmd_create_statement)
+
+    pcon = sub.add_parser("contribute", help="how to upstream a reusable statement")
+    pcon.add_argument("name", nargs="?", default=None)
+    pcon.set_defaults(func=cmd_contribute)
+
+    pb = sub.add_parser("bless", help="consciously override a protection")
+    pb.add_argument("action", choices=["push", "delete"])
+    pb.set_defaults(func=cmd_bless)
+
+    ps = sub.add_parser("sync", help="refresh the AGENTS.md digest")
+    ps.add_argument("--config", default=None)
+    ps.add_argument("--target", default="AGENTS.md")
+    ps.set_defaults(func=cmd_sync)
+
+    pd = sub.add_parser("doctor", help="check that henxels is correctly set up")
+    pd.set_defaults(func=cmd_doctor)
+
+    # Git passes arguments to its hooks (pre-push gets "<remote> <url>"); swallow them.
+    p_pc = sub.add_parser("_precommit")
+    p_pc.add_argument("hook_args", nargs="*")
+    p_pc.set_defaults(func=cmd_precommit)
+    p_pp = sub.add_parser("_prepush")
+    p_pp.add_argument("hook_args", nargs="*")
+    p_pp.set_defaults(func=cmd_prepush)
+
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 0
+    return args.func(args)
+
+
+# --- helpers -------------------------------------------------------------
+
+def _load(root: Path, config_path: str | None = None) -> Contract:
+    path = Path(config_path) if config_path else find_contract(root)
+    if path is None:
+        raise ContractError(
+            "No contract found. Looked for henxels.yaml at the repo root.\n"
+            "  Run `henxels init` to create one."
+        )
+    contract = load_contract(path)
+    apply_imports(contract, root=root)
+    return contract
+
+
+def _emit(findings: list[Finding], plain: bool = False) -> int:
+    fancy = is_fancy() and not plain
+    text = render(findings, fancy=fancy)
+    if text:
+        print(text)
+        print()
+    print(render_summary(findings, fancy=fancy))
+    blocks, _ = summarize(findings)
+    return 1 if blocks else 0
+
+
+# --- commands ------------------------------------------------------------
+
+def cmd_check(args) -> int:
+    root = Path.cwd()
+    try:
+        contract = _load(root, args.config)
+    except ContractError as exc:
+        print(exc, file=sys.stderr)
+        return 2
+
+    staged_mode = False
+    if args.paths:
+        files = [_rel(p, root) for p in args.paths]
+    elif args.staged:
+        files, staged_mode = gitinfo.staged_files(root), True
+    elif args.all:
+        files = discover(root)
+    elif gitinfo.is_git_repo(root):
+        files, staged_mode = gitinfo.staged_files(root), True
+    else:
+        files = discover(root)
+
+    if (args.paths or args.staged) and not files:
+        print("Nothing to check.")
+        return 0
+
+    # Diff-aware statements (append_only, immutable, bump_updated_on_change) only make
+    # sense against staged change — outside that, diff is None and they pass.
+    diff = staged_diff(root) if staged_mode else None
+    findings = run_contract(contract, root, files, diff=diff)
+    sim = settings.similarity(contract)
+    if sim:
+        from henxels.similarity import warn_similar
+
+        findings.extend(warn_similar(sim, root, files))
+
+    large = settings.large_files(contract)
+    if large:
+        from henxels.filesize import warn_large_files
+
+        findings.extend(warn_large_files(large, root, files))
+    return _emit(findings, plain=args.plain)
+
+
+def cmd_explain(args) -> int:
+    root = Path.cwd()
+    try:
+        contract = _load(root, args.config)
+    except ContractError as exc:
+        print(exc, file=sys.stderr)
+        return 2
+    if args.json:
+        import json
+
+        from henxels.explain import explain_data
+
+        print(json.dumps(explain_data(contract, args.path), indent=2))
+    else:
+        print(explain_path(contract, args.path))
+    return 0
+
+
+def cmd_catalogue(args) -> int:
+    from henxels.catalogue import render_catalogue
+
+    root = Path.cwd()
+    try:
+        _load(root)  # load + import so custom statements show up
+    except ContractError:
+        pass
+    print(render_catalogue())
+    return 0
+
+
+def cmd_create_statement(args) -> int:
+    from henxels.catalogue import create_statement_scaffold
+    from henxels.invocation import henxels_cmd
+
+    path, action = create_statement_scaffold(args.name, Path.cwd())
+    print(f"✓ {path.name} {action} — added a template statement '{args.name}'.")
+    print("Next:")
+    print("  • Fill in the function (it's auto-loaded — no imports: needed).")
+    print(f"  • Use it in a henxel:  {args.name}: <param>")
+    print(f"  • Reusable beyond this repo?  {henxels_cmd()} contribute {args.name}")
+    return 0
+
+
+def cmd_contribute(args) -> int:
+    from henxels.catalogue import contribute_guide, contribute_snippet
+
+    root = Path.cwd()
+    try:
+        _load(root)
+    except ContractError:
+        pass
+    print(contribute_guide(args.name))
+    if args.name:
+        snippet = contribute_snippet(args.name)
+        if snippet:
+            source, test_stub = snippet
+            print("\n--- ready-to-paste built-in (add builtin=True + a help= string) ---\n")
+            print(source)
+            print("\n--- test stub for tests/test_statements.py ---\n")
+            print(test_stub)
+    return 0
+
+
+def cmd_init(args) -> int:
+    from henxels.engine.report import BANNER
+    from henxels.scaffold import init
+
+    root = Path.cwd()
+    if is_fancy():
+        print(BANNER)
+        print()
+
+    report = init(root, install_git_hooks=not args.no_hooks, write_digest=not args.no_digest, force=args.force)
+
+    state, info = report["contract"]
+    if state == "created":
+        print(f"✓ henxels.yaml created for a {info} project")
+    else:
+        print("• henxels.yaml already exists — left as-is (use --force to replace)")
+    hooks = report.get("hooks")
+    if hooks is None:
+        print("• git hooks: skipped (not a git repo, or --no-hooks)")
+    else:
+        for hook, outcome in hooks.items():
+            mark = "✓" if outcome in ("installed", "updated") else "•"
+            print(f"{mark} git hook {hook}: {outcome}")
+    if report.get("digest"):
+        print(f"✓ AGENTS.md {report['digest']} — agents now see the contract")
+    if report.get("schema"):
+        print(f"✓ {report['schema']} — editor autocomplete for henxels.yaml")
+        print("    (install a YAML language-server extension, e.g. Red Hat YAML, to see it)")
+
+    from henxels.invocation import henxels_cmd
+
+    hx = henxels_cmd()
+    print()
+    print("Next:")
+    print(f"  • Tailor the rules: edit henxels.yaml (browse `{hx} catalogue` for statements).")
+    print(f"  • Ask what governs a spot: {hx} explain <path>")
+    print(f"  • Validate everything:    {hx} check --all")
+    print("  • To disobey a rule, change henxels.yaml — that's the whole idea.")
+    if hx != "henxels":
+        print(f"  • Tip: `uv tool install henxels` (or pipx) puts `henxels` on your PATH so you can drop `{hx.rsplit(' ', 1)[0]} `.")
+    return 0
+
+
+def cmd_doctor(args) -> int:
+    from henxels.doctor import diagnose
+
+    fancy = is_fancy()
+    all_ok = True
+    for c in diagnose(Path.cwd()):
+        mark = "✓" if c.ok else "✗"
+        all_ok = all_ok and c.ok
+        tail = f" — {c.detail}" if c.detail else ""
+        if fancy:
+            print(f"  \033[{'32' if c.ok else '31'}m{mark}\033[0m {c.label}{tail}")
+        else:
+            print(f"  {mark} {c.label}{tail}")
+    print()
+    print("henxels is ready." if all_ok else "Some checks need attention (see above).")
+    return 0 if all_ok else 1
+
+
+def cmd_sync(args) -> int:
+    from henxels.digest import sync_file
+
+    root = Path.cwd()
+    try:
+        contract = _load(root, args.config)
+    except ContractError as exc:
+        print(exc, file=sys.stderr)
+        return 2
+    action = sync_file(root / args.target, contract)
+    print(f"✓ {args.target} {action} — contract digest is in sync.")
+    return 0
+
+
+def cmd_bless(args) -> int:
+    from henxels import bless as bless_mod
+    from henxels.guard import collect_deletions
+
+    root = Path.cwd()
+    if not gitinfo.is_git_repo(root):
+        print("Not a git repo — nothing to bless here.", file=sys.stderr)
+        return 2
+
+    if args.action == "push":
+        bless_mod.bless(root, "push", gitinfo.head_sha(root) or "no-head")
+        print("✓ push blessed. Your next `git push` will go through (once).")
+        return 0
+
+    contract = None
+    try:
+        contract = _load(root)
+    except ContractError:
+        pass
+    over = (settings.delete_protection(contract) or {"over_lines": 5})["over_lines"] if contract else 5
+    deletions = collect_deletions(root, over)
+    if deletions.empty:
+        print("Nothing staged that needs a delete-bless.")
+        return 0
+    bless_mod.bless(root, "delete", deletions.fingerprint())
+    lost = deletions.files + [p for p, _ in deletions.lines]
+    print(f"✓ deletion blessed for: {', '.join(lost)}")
+    return 0
+
+
+def cmd_precommit(args) -> int:
+    from henxels.hookrun import run_precommit
+
+    code, findings = run_precommit(Path.cwd())
+    _emit(findings)
+    return code
+
+
+def cmd_prepush(args) -> int:
+    from henxels.hookrun import run_prepush
+
+    code, findings = run_prepush(Path.cwd())
+    _emit(findings)
+    return code
+
+
+def _rel(p: str, root: Path) -> str:
+    path = Path(p)
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

henxels/commands.py

@@ -0,0 +1,30 @@
+"""Run command-gate statements (run_before_commit / run_before_push).
+
+The command's own output streams to the terminal; a non-zero exit becomes a blocking
+finding. This keeps the test/lint gate in the contract — the single source of truth.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from henxels.findings import BLOCK, Finding
+
+
+def run_commands(commands: list[str], stage: str, root: Path | str) -> list[Finding]:
+    findings: list[Finding] = []
+    for command in commands:
+        result = subprocess.run(command, shell=True, cwd=str(root))
+        if result.returncode != 0:
+            findings.append(
+                Finding(
+                    level=BLOCK,
+                    henxel=f"`{command}` must pass before {stage.replace('_', ' ')}",
+                    path="",
+                    message="",
+                    details=[f"command failed (exit {result.returncode}) — fix the failure above"],
+                    steer=f"or change the run_before_{stage.split('_')[-1]} henxel in henxels.yaml",
+                )
+            )
+    return findings