obey-cli 0.1.0__py3-none-any.whl

obey_cli/config.py

@@ -0,0 +1,90 @@
+"""Read, validate and write obey.yaml."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from obey_cli.resources import schema
+
+CONFIG_NAME = "obey.yaml"
+DEFAULT_ALLOW_HOSTS = [
+    "registry.npmjs.org",
+    "pypi.org",
+    "files.pythonhosted.org",
+    "proxy.golang.org",
+    "sum.golang.org",
+    "crates.io",
+    "static.crates.io",
+    "index.crates.io",
+]
+
+
+class ConfigError(ValueError):
+    pass
+
+
+def normalise_text(text: str) -> str:
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def rule_id(text: str) -> str:
+    """A stable slug of the rule text plus a short hash, e.g. `use-pnpm-for-all-package-operations-3f9a1c`."""
+    norm = normalise_text(text)
+    slug = re.sub(r"[^a-z0-9]+", "-", norm.lower()).strip("-")[:40].strip("-") or "rule"
+    return f"{slug}-{hashlib.sha1(norm.encode()).hexdigest()[:6]}"  # noqa: S324 - an identifier, not security
+
+
+def validate(data: Any) -> list[str]:
+    import jsonschema
+
+    validator = jsonschema.Draft202012Validator(schema("obey-config-v1.json"))
+    errors = []
+    for err in sorted(validator.iter_errors(data), key=lambda e: list(e.absolute_path)):
+        where = "/".join(str(p) for p in err.absolute_path) or "(root)"
+        errors.append(f"{where}: {err.message}")
+    ids = [r.get("id") for r in (data.get("rules") or [])] if isinstance(data, dict) else []
+    dupes = sorted({i for i in ids if ids.count(i) > 1})
+    errors += [f"rules: duplicate id {d}" for d in dupes]
+    return errors
+
+
+def load(path: Path) -> dict[str, Any]:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise ConfigError(f"{path} not found; run `obey extract` first") from exc
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"{path}: invalid YAML: {exc}") from exc
+    errors = validate(data)
+    if errors:
+        raise ConfigError(f"{path}: " + "; ".join(errors[:10]))
+    assert isinstance(data, dict)
+    return data
+
+
+class _Dumper(yaml.SafeDumper):
+    pass
+
+
+def _str_presenter(dumper: yaml.SafeDumper, value: str) -> yaml.ScalarNode:
+    style = "|" if "\n" in value else None
+    return dumper.represent_scalar("tag:yaml.org,2002:str", value, style=style)
+
+
+_Dumper.add_representer(str, _str_presenter)
+
+
+def dump(data: dict[str, Any]) -> str:
+    return yaml.dump(data, Dumper=_Dumper, sort_keys=False, allow_unicode=True, width=120)
+
+
+def save(path: Path, data: dict[str, Any]) -> None:
+    errors = validate(data)
+    if errors:
+        raise ConfigError("refusing to write an invalid obey.yaml: " + "; ".join(errors[:10]))
+    path.write_text(dump(data), encoding="utf-8")

obey_cli/discover.py

@@ -0,0 +1,232 @@
+"""Find the agent instruction files in a repository and work out what each one applies to."""
+
+from __future__ import annotations
+
+import fnmatch
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from obey_cli.parse_md import ParsedFile, parse
+
+SKIP_DIRS = {
+    ".git",
+    "node_modules",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".tox",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".pytest_cache",
+    "dist",
+    "build",
+    "target",
+    ".obey",
+    ".obey-work",
+}
+MAX_IMPORT_DEPTH = 4
+
+# Which agents read which file kinds, as documented by each vendor (see docs/agents.md).
+LOADED_BY: dict[str, tuple[str, ...]] = {
+    "agents_md": ("claude-code", "codex", "opencode", "cursor", "gemini", "copilot"),
+    "claude_md": ("claude-code", "opencode"),
+    "claude_import": ("claude-code",),
+    "claude_local_md": ("claude-code",),
+    "gemini_md": ("gemini",),
+    "cursor_mdc": ("cursor",),
+    "copilot_repo": ("copilot",),
+    "copilot_path": ("copilot",),
+}
+
+# How each agent resolves several AGENTS.md files on the way from the repository root to the edited file.
+NESTED_SEMANTICS: dict[str, str] = {
+    "codex": "concatenates AGENTS.md from the repository root down to the working directory; later files win",
+    "opencode": "reads the nearest AGENTS.md walking up from the working directory",
+    "claude-code": "loads CLAUDE.md (or AGENTS.md) from the working directory upwards at start and nested files "
+    "when it reads files in their directories",
+    "cursor": "applies the nearest AGENTS.md to files below its directory",
+    "gemini": "loads context files from the working directory upwards and from subdirectories",
+    "copilot": "uses the nearest AGENTS.md in the directory tree",
+}
+
+
+@dataclass
+class InstructionFile:
+    path: str  # repository-relative POSIX path
+    kind: str
+    scope_paths: list[str]
+    loaded_by: tuple[str, ...]
+    sha256: str
+    parsed: ParsedFile
+    imported_from: str | None = None
+    activation: str = "always"  # always | globs | agent_requested | manual
+    notes: list[str] = field(default_factory=list)
+
+
+def classify(rel: str) -> str | None:
+    p = PurePosixPath(rel)
+    name = p.name
+    parts = p.parts
+    if name == "AGENTS.md":
+        return "agents_md"
+    if name == "CLAUDE.md":
+        return "claude_md"
+    if name == "CLAUDE.local.md":
+        return "claude_local_md"
+    if name == "GEMINI.md":
+        return "gemini_md"
+    if name.endswith(".mdc") and len(parts) >= 3 and parts[-3:-1] == (".cursor", "rules"):
+        return "cursor_mdc"
+    if rel == ".github/copilot-instructions.md":
+        return "copilot_repo"
+    if name.endswith(".instructions.md") and parts[:2] == (".github", "instructions"):
+        return "copilot_path"
+    return None
+
+
+def list_files(root: Path) -> list[str]:
+    """Repository-relative paths, from `git ls-files` when possible so ignored files never count."""
+    if (root / ".git").exists():
+        try:
+            out = subprocess.run(
+                ["git", "-C", str(root), "ls-files", "-co", "--exclude-standard", "-z"],
+                capture_output=True,
+                check=True,
+                timeout=60,
+            ).stdout.decode("utf-8", "replace")
+            return sorted(p for p in out.split("\0") if p and not _skipped(p))
+        except (OSError, subprocess.SubprocessError):
+            pass
+    found: list[str] = []
+    for path in root.rglob("*"):
+        rel = path.relative_to(root).as_posix()
+        if path.is_file() and not _skipped(rel):
+            found.append(rel)
+    return sorted(found)
+
+
+def _skipped(rel: str) -> bool:
+    return any(part in SKIP_DIRS for part in PurePosixPath(rel).parts[:-1])
+
+
+def _scope_for_dir(directory: str) -> list[str]:
+    return ["**"] if directory in ("", ".") else [f"{directory}/**"]
+
+
+def _split_globs(value: Any) -> list[str]:
+    if value is None or value == "":
+        return []
+    if isinstance(value, list):
+        items = [str(v) for v in value]
+    else:
+        items = [g for g in (s.strip() for s in str(value).split(",")) if g]
+    return [g.strip().strip("\"'") for g in items if g.strip()]
+
+
+def _anchor(globs: list[str], base: str) -> list[str]:
+    if base in ("", "."):
+        return globs
+    return [g if g.startswith(base + "/") else f"{base}/{g}" for g in globs]
+
+
+def _sha256(data: bytes) -> str:
+    import hashlib
+
+    return hashlib.sha256(data).hexdigest()
+
+
+def discover(root: Path, include_local: bool = False) -> list[InstructionFile]:
+    """Return every instruction file under `root`, with CLAUDE.md imports resolved."""
+    root = root.resolve()
+    result: list[InstructionFile] = []
+    seen: set[str] = set()
+    for rel in list_files(root):
+        kind = classify(rel)
+        if kind is None or rel in seen or (kind == "claude_local_md" and not include_local):
+            continue
+        data = (root / rel).read_bytes()
+        parsed = parse(data.decode("utf-8", "replace"))
+        directory = PurePosixPath(rel).parent.as_posix()
+        activation = "always"
+        notes: list[str] = []
+        if kind == "cursor_mdc":
+            base = PurePosixPath(rel).parent.parent.parent.as_posix()
+            globs = _split_globs(parsed.frontmatter.get("globs"))
+            always = str(parsed.frontmatter.get("alwaysApply", "")).lower() == "true"
+            if always:
+                scope = _scope_for_dir(base)
+            elif globs:
+                scope, activation = _anchor(globs, base), "globs"
+            elif parsed.frontmatter.get("description"):
+                scope, activation = _scope_for_dir(base), "agent_requested"
+                notes.append("applied when the agent decides the description is relevant")
+            else:
+                scope, activation = _scope_for_dir(base), "manual"
+                notes.append("applied only when referenced with @rule")
+        elif kind == "copilot_path":
+            globs = _split_globs(parsed.frontmatter.get("applyTo"))
+            scope = globs or ["**"]
+            activation = "globs" if globs else "always"
+        elif kind == "copilot_repo" or (directory == ".claude" and kind == "claude_md"):
+            scope = ["**"]
+        else:
+            scope = _scope_for_dir(directory)
+        item = InstructionFile(
+            path=rel,
+            kind=kind,
+            scope_paths=scope,
+            loaded_by=LOADED_BY[kind],
+            sha256=_sha256(data),
+            parsed=parsed,
+            activation=activation,
+            notes=notes,
+        )
+        result.append(item)
+        seen.add(rel)
+        if kind in ("claude_md", "claude_local_md", "agents_md"):
+            # Claude Code expands @imports in CLAUDE.md and, when it reads AGENTS.md, in AGENTS.md too.
+            result.extend(_resolve_imports(root, item, seen, depth=1))
+    return result
+
+
+def _resolve_imports(root: Path, parent: InstructionFile, seen: set[str], depth: int) -> list[InstructionFile]:
+    if depth > MAX_IMPORT_DEPTH:
+        return []
+    out: list[InstructionFile] = []
+    base = PurePosixPath(parent.path).parent
+    for target, _line in parent.parsed.imports:
+        if target.startswith("~") or target.startswith("/"):
+            parent.notes.append(f"import @{target} points outside the repository; not followed")
+            continue
+        rel = (base / target).as_posix()
+        resolved = (root / rel).resolve()
+        try:
+            rel = resolved.relative_to(root).as_posix()
+        except ValueError:
+            parent.notes.append(f"import @{target} points outside the repository; not followed")
+            continue
+        if rel in seen:
+            continue
+        if not resolved.is_file():
+            parent.notes.append(f"import @{target} not found")
+            continue
+        data = resolved.read_bytes()
+        child = InstructionFile(
+            path=rel,
+            kind="claude_import",
+            scope_paths=list(parent.scope_paths),
+            loaded_by=LOADED_BY["claude_import"],
+            sha256=_sha256(data),
+            parsed=parse(data.decode("utf-8", "replace")),
+            imported_from=parent.path,
+        )
+        seen.add(rel)
+        out.append(child)
+        out.extend(_resolve_imports(root, child, seen, depth + 1))
+    return out
+
+
+def scope_matches(scope_paths: list[str], path: str) -> bool:
+    return any(fnmatch.fnmatchcase(path, g) or (g.endswith("/**") and path.startswith(g[:-2])) for g in scope_paths)

obey_cli/enforce/__init__.py

@@ -0,0 +1,114 @@
+"""Compile rules into hooks for each agent plus an agent-agnostic pre-commit check."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+from typing import Any
+
+from obey_cli import __version__
+from obey_cli.enforce.merge import Plan
+from obey_cli.enforce.targets import EDIT_TYPES, SHELL_TYPES, STOP_TYPES, TARGETS
+
+HOOK_DIR = ".obey/hooks"
+TEMPLATES = Path(__file__).parent / "templates"
+ENGINE = Path(__file__).parent / "engine" / "obey_engine.py"
+MECHANICAL = SHELL_TYPES | EDIT_TYPES | STOP_TYPES
+GITIGNORE = "backup/\nledger.jsonl\nruns/\nreport.*\n"
+
+
+def compiled(rules: Sequence[dict[str, Any]]) -> dict[str, Any]:
+    body = [{"id": r["id"], "text": r["text"], "source": r["source"], "checker": r["checker"]} for r in rules]
+    digest = hashlib.sha256(json.dumps(body, sort_keys=True).encode()).hexdigest()
+    return {"obey_version": __version__, "rules_sha256": digest, "rules": body}
+
+
+def select(
+    config: dict[str, Any],
+    *,
+    report: dict[str, Any] | None = None,
+    ids: Iterable[str] | None = None,
+    threshold: float = 1.0,
+) -> list[dict[str, Any]]:
+    """Active rules with a mechanical checker; with a report, only those broken in some exercised run."""
+    active = [
+        r
+        for r in config.get("rules", [])
+        if r.get("status") == "active" and r.get("checker") and r["checker"]["type"] in MECHANICAL
+    ]
+    if ids is not None:
+        wanted = set(ids)
+        return [r for r in active if r["id"] in wanted]
+    if report is None:
+        return active
+    broken = {
+        s["rule_id"]
+        for s in report.get("scores", [])
+        if s.get("arm") == "rule" and s.get("compliance") is not None and s["compliance"] < threshold
+    }
+    return [r for r in active if r["id"] in broken]
+
+
+def advisory(rules: Sequence[dict[str, Any]], targets: Sequence[str]) -> list[dict[str, str]]:
+    """Rules a target cannot enforce mechanically (listed as advisory only)."""
+    out = []
+    for r in rules:
+        kind = r["checker"]["type"]
+        for name in targets:
+            t = TARGETS[name]
+            stop_only = kind in STOP_TYPES and kind not in (SHELL_TYPES | EDIT_TYPES)
+            if (stop_only and not t.stop and name != "precommit") or (
+                name == "precommit" and kind in ("command_required", "final_message", "no_push", "no_commit")
+            ):
+                out.append({"rule_id": r["id"], "target": name, "reason": f"{t.display} cannot block {kind}"})
+    return out
+
+
+def plan_enforce(root: Path, rules: Sequence[dict[str, Any]], targets: Sequence[str]) -> Plan:
+    plan = Plan(root)
+    plan.put(f"{HOOK_DIR}/obey_hook.py", (TEMPLATES / "obey_hook.py").read_text(encoding="utf-8"))
+    plan.put(f"{HOOK_DIR}/obey_engine.py", ENGINE.read_text(encoding="utf-8"))
+    plan.put(f"{HOOK_DIR}/rules.json", json.dumps(compiled(rules), indent=2) + "\n")
+    plan.put(".obey/.gitignore", GITIGNORE)
+    if "precommit" in targets:
+        plan.put(".obey/pre-commit", (TEMPLATES / "pre_commit.py").read_text(encoding="utf-8"))
+    elif (root / ".obey/pre-commit").exists():
+        plan.put(".obey/pre-commit", None)
+    for name in targets:
+        TARGETS[name].write(plan, rules)
+    for name, target in TARGETS.items():
+        if name not in targets:
+            target.remove(plan)
+    return plan
+
+
+def plan_remove(root: Path) -> Plan:
+    plan = Plan(root)
+    for target in TARGETS.values():
+        target.remove(plan)
+    for rel in (f"{HOOK_DIR}/obey_hook.py", f"{HOOK_DIR}/obey_engine.py", f"{HOOK_DIR}/rules.json", ".obey/pre-commit"):
+        if (root / rel).exists():
+            plan.put(rel, None)
+    return plan
+
+
+def in_sync(root: Path, rules: Sequence[dict[str, Any]], targets: Sequence[str]) -> list[str]:
+    """Files whose content differs from what `obey enforce` would write now (empty when in sync)."""
+    plan = plan_enforce(root, rules, targets)
+    return sorted(plan.changes)
+
+
+def installed_targets(root: Path) -> list[str]:
+    found = []
+    for name, target in TARGETS.items():
+        for rel in target.files:
+            path = root / rel
+            if path.exists() and ".obey/hooks/obey_hook.py" in path.read_text(encoding="utf-8", errors="replace"):
+                found.append(name)
+                break
+            if name == "precommit" and path.exists():
+                found.append(name)
+                break
+    return found