tears-cli 0.1.0__py3-none-any.whl

tears/config.py

@@ -0,0 +1,235 @@
+# @tear: 3
+"""`.tears.toml` parsing and validation."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, cast
+
+CONFIG_FILENAME = ".tears.toml"
+MISSING_HEADER_VALUES = ("warn", "error")
+
+
+def _path_segments(path: str) -> tuple[str, ...]:
+    return tuple(p for p in path.strip("/").split("/") if p)
+
+
+class ConfigError(ValueError):
+    """Raised when `.tears.toml` is malformed or fails schema validation."""
+
+
+@dataclass(frozen=True)
+class TearsConfig:
+    """Validated, resolved tears configuration.
+
+    `directory_requirements` keys are normalized (trailing slashes stripped).
+    `import_rules` is the raw, possibly-partial mapping; use
+    `resolved_import_rules()` to get the full per-tier allow-set with defaults filled in.
+    """
+
+    max_tear: int = 3
+    directory_requirements: dict[str, int] = field(default_factory=lambda: {})
+    exclude: list[str] = field(default_factory=lambda: [])
+    source_roots: list[str] = field(default_factory=lambda: ["."])
+    import_rules: dict[int, int] | None = None
+    missing_header: str = "warn"
+    default_tear: int | None = None
+    default_tears: dict[str, int] = field(default_factory=lambda: {})
+
+    def __post_init__(self) -> None:
+        if self.max_tear < 1:
+            raise ConfigError(f"max_tear must be at least 1, got {self.max_tear}")
+        if self.missing_header not in MISSING_HEADER_VALUES:
+            raise ConfigError(
+                f"missing_header must be one of {MISSING_HEADER_VALUES}, "
+                f"got {self.missing_header!r}"
+            )
+        for path, tier in self.directory_requirements.items():
+            if not 0 <= tier <= self.max_tear:
+                raise ConfigError(
+                    f"directory_requirements[{path!r}] = {tier}: "
+                    f"tear level {tier} exceeds max_tear {self.max_tear}"
+                )
+        if self.import_rules is not None:
+            for importer, max_allowed in self.import_rules.items():
+                if not 0 <= importer <= self.max_tear:
+                    raise ConfigError(
+                        f"import_rules key {importer}: "
+                        f"tear level {importer} exceeds max_tear {self.max_tear}"
+                    )
+                if not 0 <= max_allowed <= self.max_tear:
+                    raise ConfigError(
+                        f"import_rules[{importer}] = {max_allowed}: "
+                        f"max_allowed {max_allowed} exceeds max_tear {self.max_tear}"
+                    )
+        if self.default_tear is not None and not 0 <= self.default_tear <= self.max_tear:
+            raise ConfigError(f"default_tear {self.default_tear} exceeds max_tear {self.max_tear}")
+        for path, tear in self.default_tears.items():
+            if not 0 <= tear <= self.max_tear:
+                raise ConfigError(
+                    f"default_tears[{path!r}] = {tear}: "
+                    f"tear level {tear} exceeds max_tear {self.max_tear}"
+                )
+
+    def resolved_import_rules(self) -> dict[int, frozenset[int]]:
+        """Full matrix with defaults filled in for any unspecified tier."""
+        resolved: dict[int, frozenset[int]] = {}
+        for tier in range(self.max_tear + 1):
+            if self.import_rules is not None and tier in self.import_rules:
+                resolved[tier] = frozenset(range(self.import_rules[tier] + 1))
+            else:
+                resolved[tier] = frozenset(range(tier + 1))
+        return resolved
+
+    def resolve_missing_tier(self, rel_path: str) -> tuple[int, bool]:
+        """Return (effective_tier, was_defaulted) for a file with no @tear header.
+
+        Lookup order: longest-prefix match in default_tears → global default_tear
+        → max_tear (not defaulted; caller should emit the missing-header warning).
+        """
+        file_segs = _path_segments(rel_path)
+        longest_len = -1
+        matched: int | None = None
+        for dir_key, tier in self.default_tears.items():
+            dir_segs = _path_segments(dir_key)
+            if len(dir_segs) > len(file_segs):
+                continue
+            if file_segs[: len(dir_segs)] != dir_segs:
+                continue
+            if len(dir_segs) > longest_len:
+                longest_len = len(dir_segs)
+                matched = tier
+        if matched is not None:
+            return matched, True
+        if self.default_tear is not None:
+            return self.default_tear, True
+        return self.max_tear, False
+
+
+def load_config(repo_root: Path) -> TearsConfig:
+    """Load `.tears.toml` from `repo_root`. Missing file => defaults.
+
+    Malformed TOML or a schema failure raises `ConfigError` with a clear message
+    naming the file and the problem.
+    """
+    config_path = repo_root / CONFIG_FILENAME
+    if not config_path.exists():
+        return TearsConfig()
+
+    try:
+        raw = tomllib.loads(config_path.read_text())
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{CONFIG_FILENAME}: malformed TOML: {exc}") from exc
+
+    return _from_mapping(raw, source=CONFIG_FILENAME)
+
+
+def _from_mapping(raw: dict[str, Any], *, source: str) -> TearsConfig:
+    kwargs: dict[str, Any] = {}
+
+    if "max_tear" in raw:
+        kwargs["max_tear"] = _require_int(raw["max_tear"], "max_tear", source)
+
+    if "directory_requirements" in raw:
+        dr_raw = _require_mapping(raw["directory_requirements"], "directory_requirements", source)
+        normalized: dict[str, int] = {}
+        for key, value in dr_raw.items():
+            if not isinstance(key, str) or not isinstance(value, int) or isinstance(value, bool):
+                raise ConfigError(
+                    f"{source}: directory_requirements entries must be str -> int, "
+                    f"got {key!r} -> {value!r}"
+                )
+            normalized[key.rstrip("/")] = value
+        kwargs["directory_requirements"] = normalized
+
+    if "exclude" in raw:
+        exclude_raw = _require_list(raw["exclude"], "exclude", source)
+        exclude: list[str] = []
+        for item in exclude_raw:
+            if not isinstance(item, str):
+                raise ConfigError(f"{source}: exclude entries must be strings, got {item!r}")
+            exclude.append(item)
+        kwargs["exclude"] = exclude
+
+    if "imports" in raw:
+        imports_raw = _require_mapping(raw["imports"], "imports", source)
+        if "source_roots" in imports_raw:
+            sr_raw = imports_raw["source_roots"]
+            if not isinstance(sr_raw, list):
+                raise ConfigError(
+                    f"{source}: imports.source_roots must be a list, got {type(sr_raw).__name__}"
+                )
+            source_roots: list[str] = []
+            for item in cast(list[Any], sr_raw):
+                if not isinstance(item, str):
+                    raise ConfigError(
+                        f"{source}: imports.source_roots entries must be strings, got {item!r}"
+                    )
+                source_roots.append(item)
+            kwargs["source_roots"] = source_roots
+
+    if "import_rules" in raw:
+        ir_raw = _require_mapping(raw["import_rules"], "import_rules", source)
+        rules: dict[int, int] = {}
+        for key, value in ir_raw.items():
+            # TOML keys are always strings; convert to int.
+            try:
+                key_int = int(cast(str, key))
+            except (ValueError, TypeError) as exc:
+                raise ConfigError(
+                    f"{source}: import_rules keys must be integer-valued strings, got {key!r}"
+                ) from exc
+            if not isinstance(value, int) or isinstance(value, bool):
+                raise ConfigError(
+                    f"{source}: import_rules[{key_int}] must be an int, got {type(value).__name__}"
+                )
+            rules[key_int] = value
+        kwargs["import_rules"] = rules
+
+    if "missing_header" in raw:
+        kwargs["missing_header"] = _require_str(raw["missing_header"], "missing_header", source)
+
+    if "default_tear" in raw:
+        kwargs["default_tear"] = _require_int(raw["default_tear"], "default_tear", source)
+
+    if "default_tears" in raw:
+        dt_raw = _require_mapping(raw["default_tears"], "default_tears", source)
+        default_tears: dict[str, int] = {}
+        for key, value in dt_raw.items():
+            if not isinstance(key, str) or not isinstance(value, int) or isinstance(value, bool):
+                raise ConfigError(
+                    f"{source}: default_tears entries must be str -> int, got {key!r} -> {value!r}"
+                )
+            default_tears[key.rstrip("/")] = value
+        kwargs["default_tears"] = default_tears
+
+    try:
+        return TearsConfig(**kwargs)
+    except ConfigError as exc:
+        raise ConfigError(f"{source}: {exc}") from None
+
+
+def _require_int(value: Any, key: str, source: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ConfigError(f"{source}: {key} must be int, got {type(value).__name__}")
+    return value
+
+
+def _require_str(value: Any, key: str, source: str) -> str:
+    if not isinstance(value, str):
+        raise ConfigError(f"{source}: {key} must be str, got {type(value).__name__}")
+    return value
+
+
+def _require_mapping(value: Any, key: str, source: str) -> dict[Any, Any]:
+    if not isinstance(value, dict):
+        raise ConfigError(f"{source}: {key} must be a mapping, got {type(value).__name__}")
+    return cast(dict[Any, Any], value)
+
+
+def _require_list(value: Any, key: str, source: str) -> list[Any]:
+    if not isinstance(value, list):
+        raise ConfigError(f"{source}: {key} must be a list, got {type(value).__name__}")
+    return cast(list[Any], value)

tears/exclude.py

@@ -0,0 +1,38 @@
+# @tear: 2
+"""Exclude-pattern matching shared by the graph builder and the Claude hook.
+
+Patterns are fnmatch-style with `**` extended to match across path separators
+(`**/foo.py` matches `a/b/c/foo.py`). Paths are matched relative to the repo root
+in POSIX form.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from pathlib import Path
+
+
+def is_excluded(file_path: Path, repo_root: Path, patterns: list[str]) -> bool:
+    """True if `file_path` matches any of `patterns` relative to `repo_root`."""
+    if not patterns:
+        return False
+    try:
+        rel = file_path.relative_to(repo_root).as_posix()
+    except ValueError:
+        try:
+            rel = file_path.resolve().relative_to(repo_root.resolve()).as_posix()
+        except ValueError:
+            return False
+    return any(_match_glob(rel, p) for p in patterns)
+
+
+def _match_glob(path: str, pattern: str) -> bool:
+    return re.compile(_glob_to_regex(pattern)).fullmatch(path) is not None
+
+
+def _glob_to_regex(pattern: str) -> str:
+    placeholder = "\x00DOUBLESTAR\x00"
+    p = pattern.replace("**", placeholder)
+    p = fnmatch.translate(p).rstrip("\\Z")
+    return p.replace(re.escape(placeholder), ".*")

tears/graph/__init__.py

@@ -0,0 +1,42 @@
+# @tear: 3
+"""Import graph abstraction.
+
+The checker depends on the `ImportGraph` Protocol; concrete builders (currently
+`grimp_builder.GrimpImportGraph`) implement it. This lets us swap builders
+without touching checker logic.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Protocol
+
+
+class ImportGraph(Protocol):
+    """Builders provide repo-wide tier and import data."""
+
+    def files(self) -> Iterable[Path]:
+        """All in-scope Python files in the repo (excluded files omitted)."""
+        ...
+
+    def tier_of(self, file: Path) -> int | None:
+        """Tier from the file's @tear header, or None if missing/malformed."""
+        ...
+
+    def imports_of(self, file: Path) -> Iterable[Path]:
+        """Files this file directly imports — resolved to repo files.
+
+        Unresolvable targets (stdlib, third-party, dynamic) and excluded targets
+        are omitted.
+        """
+        ...
+
+    def importers_of(self, file: Path) -> Iterable[Path]:
+        """Files that directly import this file. Builders may raise
+        NotImplementedError if reverse-dep queries aren't needed by the checker.
+        """
+        ...
+
+
+__all__ = ["ImportGraph"]

tears/graph/grimp_builder.py

@@ -0,0 +1,145 @@
+# @tear: 3
+"""grimp-backed `ImportGraph` implementation.
+
+Builds the graph by:
+1. Walking the configured `source_roots` to discover top-level Python packages.
+2. Calling `grimp.build_graph(*pkgs)` to get all imports.
+3. Mapping grimp's dotted module names back to absolute repo file paths.
+4. Parsing each file's `@tear` header.
+5. Applying the `exclude` patterns so excluded files are invisible to the checker.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import subprocess
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any, cast
+
+import grimp
+
+from tears.config import TearsConfig
+from tears.exclude import is_excluded
+from tears.header import parse_tear_level
+
+
+class GrimpImportGraph:
+    """`ImportGraph` over a real repo, backed by grimp."""
+
+    def __init__(
+        self,
+        *,
+        files: dict[Path, int | None],
+        imports: dict[Path, frozenset[Path]],
+        importers: dict[Path, frozenset[Path]],
+    ) -> None:
+        self._files = files
+        self._imports = imports
+        self._importers = importers
+
+    def files(self) -> Iterable[Path]:
+        return self._files.keys()
+
+    def tier_of(self, file: Path) -> int | None:
+        return self._files.get(file)
+
+    def imports_of(self, file: Path) -> Iterable[Path]:
+        return self._imports.get(file, frozenset())
+
+    def importers_of(self, file: Path) -> Iterable[Path]:
+        return self._importers.get(file, frozenset())
+
+
+def build_grimp_graph(repo_root: Path, config: TearsConfig) -> GrimpImportGraph:
+    """Build the import graph for `repo_root` under `config`."""
+    repo_root = repo_root.resolve()
+    source_root_paths = [(repo_root / r).resolve() for r in config.source_roots]
+
+    packages: list[tuple[str, Path]] = []
+    for sr in source_root_paths:
+        if not sr.is_dir():
+            continue
+        for child in sorted(sr.iterdir()):
+            if (
+                child.is_dir()
+                and (child / "__init__.py").exists()
+                and not _git_ignored(child, repo_root)
+            ):
+                packages.append((child.name, sr))
+
+    if not packages:
+        return GrimpImportGraph(files={}, imports={}, importers={})
+
+    sys_path_added: list[str] = []
+    for sr in source_root_paths:
+        sr_str = str(sr)
+        if sr_str not in sys.path:
+            sys.path.insert(0, sr_str)
+            sys_path_added.append(sr_str)
+
+    try:
+        package_names = [name for name, _ in packages]
+        graph = cast(Any, grimp.build_graph(*package_names))  # pyright: ignore[reportUnknownMemberType]
+    finally:
+        for sr_str in sys_path_added:
+            with contextlib.suppress(ValueError):
+                sys.path.remove(sr_str)
+
+    package_roots = {name: sr / name for name, sr in packages}
+    module_to_file = _build_module_index(package_roots)
+
+    files: dict[Path, int | None] = {}
+    for file_path in module_to_file.values():
+        if is_excluded(file_path, repo_root, config.exclude):
+            continue
+        files[file_path] = parse_tear_level(file_path.read_text(), max_tear=config.max_tear)
+
+    imports: dict[Path, set[Path]] = {f: set() for f in files}
+    importers: dict[Path, set[Path]] = {f: set() for f in files}
+
+    file_to_module = {f: m for m, f in module_to_file.items()}
+
+    for file_path in files:
+        module = file_to_module[file_path]
+        for imported_module in graph.find_modules_directly_imported_by(module):
+            target = module_to_file.get(imported_module)
+            if target is None or target not in files:
+                continue
+            imports[file_path].add(target)
+            importers[target].add(file_path)
+
+    return GrimpImportGraph(
+        files=files,
+        imports={k: frozenset(v) for k, v in imports.items()},
+        importers={k: frozenset(v) for k, v in importers.items()},
+    )
+
+
+def _build_module_index(package_roots: dict[str, Path]) -> dict[str, Path]:
+    """Map every reachable module name to its source file."""
+    index: dict[str, Path] = {}
+    for pkg_name, pkg_root in package_roots.items():
+        for py_file in pkg_root.rglob("*.py"):
+            rel = py_file.relative_to(pkg_root)
+            parts = rel.with_suffix("").parts
+            if parts[-1] == "__init__":
+                parts = parts[:-1]
+            module = ".".join((pkg_name, *parts)) if parts else pkg_name
+            index[module] = py_file.resolve()
+    return index
+
+
+def _git_ignored(path: Path, repo_root: Path) -> bool:
+    """Return True if `path` is ignored by git, False if not or if git is unavailable."""
+    try:
+        result = subprocess.run(
+            ["git", "check-ignore", "-q", "--", str(path)],
+            capture_output=True,
+            cwd=repo_root,
+            timeout=5,
+        )
+        return result.returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False

tears/header.py

@@ -0,0 +1,30 @@
+# @tear: 3
+"""Parse the `@tear` header from a Python source file."""
+
+from __future__ import annotations
+
+import re
+
+HEADER_RE = re.compile(r"^[ \t]*#[ \t]*@tear:[ \t]*(\d+)(?![\w.])")
+
+MAX_LINES = 5
+
+
+def parse_tear_level(content: str, *, max_tear: int = 3) -> int | None:
+    """Return the worst (highest) valid tier found in the first 5 lines, else None.
+
+    A valid header is a line whose first non-whitespace token is `#`, followed by
+    `@tear: <digits>`, where digits parse as an integer in [0, max_tear]. Out-of-range
+    values are treated as malformed (not as that integer). `1.5` and `-1` do not match.
+    """
+    worst: int | None = None
+    for line in content.splitlines()[:MAX_LINES]:
+        match = HEADER_RE.match(line)
+        if match is None:
+            continue
+        value = int(match.group(1))
+        if value < 0 or value > max_tear:
+            continue
+        if worst is None or value > worst:
+            worst = value
+    return worst

tears/hook.py

@@ -0,0 +1,84 @@
+# @tear: 3
+"""Claude Code PostToolUse hook for tears.
+
+Demotes the `@tear` header in every file Claude writes or edits to `max_tear`
+(default 3). This is the enforcement backstop: a human reviewing the resulting
+diff must consciously re-promote the tier to attest that they read the code.
+If they leave the demotion in place, that's the attestation that they didn't.
+
+Invocation:
+- As a Claude Code hook: receives a JSON payload on stdin describing the tool
+  call (`{"tool_input": {"file_path": "..."}, ...}`). Register in
+  `.claude/settings.json` under `hooks.PostToolUse`.
+- Manually: `python -m tears.hook FILE [FILE ...]`. Useful for testing and
+  bulk-demoting a list of files.
+
+Behavior:
+- **Silent on bad input.** Empty stdin, malformed JSON, missing fields, paths
+  that don't exist, and excluded paths all return 0 with no output.
+- **Broken `.tears.toml` is non-fatal.** Falls back to `TearsConfig()` defaults.
+
+The mutation logic lives in `tears.mutate`; this module is the entry point only.
+`set_tear` and `process_file` are re-exported here for backward compatibility.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, cast
+
+from tears.config import ConfigError, TearsConfig, load_config
+from tears.mutate import find_repo_root, process_file
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point. Reads file paths from argv, or stdin JSON if none provided."""
+    if argv is None:
+        argv = sys.argv[1:]
+
+    paths: list[Path] = [Path(arg) for arg in argv] if argv else _paths_from_stdin()
+    if not paths:
+        return 0
+
+    repo_root = find_repo_root(paths[0])
+    try:
+        config = load_config(repo_root)
+    except ConfigError:
+        config = TearsConfig()
+
+    for path in paths:
+        try:
+            process_file(
+                path,
+                tear=config.max_tear,
+                exclude=config.exclude,
+                repo_root=repo_root,
+            )
+        except OSError:
+            continue
+    return 0
+
+
+def _paths_from_stdin() -> list[Path]:
+    raw = sys.stdin.read().strip()
+    if not raw:
+        return []
+    try:
+        payload: Any = json.loads(raw)
+    except json.JSONDecodeError:
+        return []
+    if not isinstance(payload, dict):
+        return []
+    tool_input = cast(dict[str, Any], payload).get("tool_input")
+    if not isinstance(tool_input, dict):
+        return []
+    file_path = cast(dict[str, Any], tool_input).get("file_path")
+    if isinstance(file_path, str):
+        return [Path(file_path)]
+    return []
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())