tears-cli 0.1.0a1__tar.gz

tears_cli-0.1.0a1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.3
+Name: tears-cli
+Version: 0.1.0a1
+Summary: Tiered Enforcement, Authorship Review System — vibe-code responsibly.
+Author: Hillel Twersky
+Author-email: Hillel Twersky <35217356+Thillel@users.noreply.github.com>
+Requires-Dist: grimp>=3.4
+Requires-Python: >=3.11

tears_cli-0.1.0a1/pyproject.toml

@@ -0,0 +1,50 @@
+# @tear: 1
+[project]
+name = "tears-cli"
+version = "0.1.0a1"
+description = "Tiered Enforcement, Authorship Review System — vibe-code responsibly."
+authors = [
+    { name = "Hillel Twersky", email = "35217356+Thillel@users.noreply.github.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "grimp>=3.4",
+]
+
+[project.scripts]
+tears = "tears.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.7",
+    "pyright>=1.1.380",
+    "pre-commit>=4.6.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = ["tests/scan/fixtures"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.pyright]
+include = ["src", "tests"]
+exclude = ["tests/scan/fixtures"]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+
+[build-system]
+requires = ["uv_build>=0.10.5,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "tears"
+module-root = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

tears_cli-0.1.0a1/src/tears/__init__.py

@@ -0,0 +1 @@
+# @tear: 3

tears_cli-0.1.0a1/src/tears/__main__.py

@@ -0,0 +1,4 @@
+# @tear: 3
+from tears.cli import main
+
+raise SystemExit(main())

tears_cli-0.1.0a1/src/tears/checker.py

@@ -0,0 +1,135 @@
+# @tear: 3
+"""The pure checker: ImportGraph + TearsConfig -> list of FileReports.
+
+This module knows nothing about the filesystem, parsing, or output formatting.
+It composes the rule functions over the data the graph exposes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from tears.config import TearsConfig
+from tears.graph import ImportGraph
+from tears.rules import can_import, check_directory_requirement
+
+Severity = Literal["fail", "warn"]
+Status = Literal["ok", "warn", "fail"]
+
+
+@dataclass(frozen=True)
+class Issue:
+    severity: Severity
+    message: str
+
+
+@dataclass(frozen=True)
+class FileReport:
+    path: Path
+    tier: int | None
+    issues: tuple[Issue, ...] = field(default_factory=lambda: ())
+
+    @property
+    def status(self) -> Status:
+        if any(i.severity == "fail" for i in self.issues):
+            return "fail"
+        if any(i.severity == "warn" for i in self.issues):
+            return "warn"
+        return "ok"
+
+
+@dataclass(frozen=True)
+class CheckReport:
+    files: tuple[FileReport, ...]
+
+    @property
+    def exit_code(self) -> int:
+        return 1 if any(f.status == "fail" for f in self.files) else 0
+
+    @property
+    def failure_count(self) -> int:
+        return sum(1 for f in self.files if f.status == "fail")
+
+    @property
+    def warning_count(self) -> int:
+        return sum(1 for f in self.files if f.status == "warn")
+
+
+def check(
+    graph: ImportGraph,
+    config: TearsConfig,
+    *,
+    repo_root: Path,
+) -> CheckReport:
+    """Run all v1 checks: missing headers, directory requirements, import tiers."""
+    resolved_rules = config.resolved_import_rules()
+    missing_severity: Severity = "fail" if config.missing_header == "error" else "warn"
+
+    reports: list[FileReport] = []
+    for file_path in sorted(graph.files(), key=str):
+        tier = graph.tier_of(file_path)
+        effective_tier = tier if tier is not None else config.max_tear
+        issues: list[Issue] = []
+
+        if tier is None:
+            issues.append(
+                Issue(
+                    severity=missing_severity,
+                    message=f"missing @tear header (treated as tear {config.max_tear})",
+                )
+            )
+
+        rel_path = _relative_posix(file_path, repo_root)
+        if not check_directory_requirement(rel_path, effective_tier, config.directory_requirements):
+            required = _required_tier(rel_path, config.directory_requirements)
+            issues.append(
+                Issue(
+                    severity="fail",
+                    message=f"directory requires tear {required}, file is tear {effective_tier}",
+                )
+            )
+
+        for target in sorted(graph.imports_of(file_path), key=str):
+            target_tier = graph.tier_of(target)
+            target_effective = target_tier if target_tier is not None else config.max_tear
+            if can_import(effective_tier, target_effective, resolved_rules):
+                continue
+            target_rel = _relative_posix(target, repo_root)
+            issues.append(
+                Issue(
+                    severity="fail",
+                    message=(
+                        f"imports {target_rel} (tear {target_effective}): "
+                        f"tear {effective_tier} cannot import from tear {target_effective}"
+                    ),
+                )
+            )
+
+        reports.append(FileReport(path=file_path, tier=tier, issues=tuple(issues)))
+
+    return CheckReport(files=tuple(reports))
+
+
+def _relative_posix(path: Path, root: Path) -> str:
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def _required_tier(rel_path: str, requirements: dict[str, int]) -> int | None:
+    file_segments = tuple(p for p in rel_path.strip("/").split("/") if p)
+    longest_match: int | None = None
+    longest_len = -1
+    for dir_key, required_tier in requirements.items():
+        dir_segments = tuple(p for p in dir_key.strip("/").split("/") if p)
+        if len(dir_segments) > len(file_segments):
+            continue
+        if file_segments[: len(dir_segments)] != dir_segments:
+            continue
+        if len(dir_segments) > longest_len:
+            longest_len = len(dir_segments)
+            longest_match = required_tier
+    return longest_match

tears_cli-0.1.0a1/src/tears/cli.py

@@ -0,0 +1,39 @@
+# @tear: 3
+"""`tears` — bare CLI entry point. No subcommands in v1."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from tears.config import ConfigError
+from tears.scan import run_scan
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="tears",
+        description="Tiered Enforcement, Authorship Review System — scan a repo.",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Path to scan (defaults to the current directory).",
+    )
+    args = parser.parse_args(argv)
+
+    repo_root = Path(args.path).resolve()
+    try:
+        report, output = run_scan(repo_root)
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    sys.stdout.write(output)
+    return report.exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tears_cli-0.1.0a1/src/tears/config.py

@@ -0,0 +1,184 @@
+# @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")
+
+
+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"
+
+    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}"
+                    )
+
+    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 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, "
+                    f"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)
+
+    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_cli-0.1.0a1/src/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_cli-0.1.0a1/src/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_cli-0.1.0a1/src/tears/graph/grimp_builder.py

@@ -0,0 +1,126 @@
+# @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 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():
+                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

tears_cli-0.1.0a1/src/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_cli-0.1.0a1/src/tears/hook.py

@@ -0,0 +1,318 @@
+# @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.
+
+Scope:
+- **Replacement is universal.** Any file with an existing `@tear: <digit>` header
+  in any line-comment style (`#`, `//`, `--`, `;`) or block-comment style
+  (`<!-- ... -->`, `/* ... */`) gets its digit rewritten to `max_tear`.
+- **Insertion is type-specific.** A file *without* a header gets a new one
+  inserted if its extension or filename is in `COMMENT_STYLES` /
+  `FILENAME_STYLES` — covers most common dev files: Python, JS/TS, Go, Rust,
+  C/C++/C#, Java, Kotlin, Swift, Ruby, Shell, TOML, YAML, INI, SQL, Lua,
+  HTML/XML/Markdown/SVG, CSS/SCSS, Makefile, Dockerfile, .gitignore, .env, etc.
+- **Multi-language scanning is still v2.** The hook covers many comment styles
+  cheaply; the *scanner* (`tears`) still only enforces import rules on `.py`.
+  See plan §1 for the asymmetric-scope rationale.
+
+Behavior:
+- **Matcher.** `.claude/settings.json` matches `Edit|Write|MultiEdit` only. Doesn't
+  catch `NotebookEdit` or any future file-touching tool — extend the matcher if
+  you need them.
+- **One file per invocation.** `Edit`, `Write`, and `MultiEdit` each operate on a
+  single `tool_input.file_path` (MultiEdit applies multiple edits to one file).
+  The stdin parser returns a 1-element list. A future bulk-edit tool with a list
+  payload would need parser changes.
+- **Silent on bad input.** Empty stdin, malformed JSON, missing fields, paths
+  that don't exist, and excluded paths all return 0 with no output. The hook
+  never breaks Claude Code's flow.
+- **Broken `.tears.toml` is non-fatal.** Falls back to `TearsConfig()` defaults so
+  a malformed config can't stop Claude from editing files. The `tears` CLI
+  itself still hard-fails on a broken config — only the hook is lenient.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, cast
+
+from tears.config import ConfigError, TearsConfig, load_config
+from tears.exclude import is_excluded
+
+# Match a line whose first non-whitespace token looks like a comment marker
+# (one or more non-alphanumeric non-whitespace chars), followed by `@tear:` and
+# digits. Captures the full prefix and the digits separately so we can rewrite
+# the digit in place. The non-alphanumeric requirement keeps us from matching
+# `@tear: 1` inside a string literal like `x = "@tear: 1"`.
+LINE_HEADER_RE = re.compile(
+    r"^([ \t]*[^A-Za-z0-9\s]+[ \t]*@tear:[ \t]*)(\d+)"
+)
+SHEBANG_RE = re.compile(r"^#!")
+ENCODING_RE = re.compile(r"coding[=:]\s*[-\w.]+")
+
+MAX_LINES = 5
+
+# Extensions where we know how to *insert* a fresh header. Replacement works
+# universally; only insertion needs the comment markers. Each value is
+# (opener, closer) — `closer` is None for line comments (`#`, `//`, `--`, `;`)
+# and a string for block comments (`<!-- ... -->`, `/* ... */`).
+CommentStyle = tuple[str, str | None]
+
+COMMENT_STYLES: dict[str, CommentStyle] = {
+    # Hash line comment
+    ".py": ("#", None),
+    ".rb": ("#", None),
+    ".pl": ("#", None),
+    ".sh": ("#", None),
+    ".bash": ("#", None),
+    ".zsh": ("#", None),
+    ".fish": ("#", None),
+    ".toml": ("#", None),
+    ".yml": ("#", None),
+    ".yaml": ("#", None),
+    ".r": ("#", None),
+    ".ex": ("#", None),
+    ".exs": ("#", None),
+    # Double-slash line comment
+    ".js": ("//", None),
+    ".mjs": ("//", None),
+    ".cjs": ("//", None),
+    ".ts": ("//", None),
+    ".tsx": ("//", None),
+    ".jsx": ("//", None),
+    ".go": ("//", None),
+    ".rs": ("//", None),
+    ".java": ("//", None),
+    ".kt": ("//", None),
+    ".swift": ("//", None),
+    ".c": ("//", None),
+    ".cpp": ("//", None),
+    ".cc": ("//", None),
+    ".cxx": ("//", None),
+    ".h": ("//", None),
+    ".hpp": ("//", None),
+    ".cs": ("//", None),
+    ".scala": ("//", None),
+    ".dart": ("//", None),
+    ".zig": ("//", None),
+    # Double-dash line comment
+    ".sql": ("--", None),
+    ".lua": ("--", None),
+    ".hs": ("--", None),
+    ".elm": ("--", None),
+    # Semicolon line comment
+    ".ini": (";", None),
+    ".cfg": (";", None),
+    ".clj": (";", None),
+    ".lisp": (";", None),
+    # HTML / XML / Markdown block comment
+    ".html": ("<!--", "-->"),
+    ".htm": ("<!--", "-->"),
+    ".xml": ("<!--", "-->"),
+    ".md": ("<!--", "-->"),
+    ".markdown": ("<!--", "-->"),
+    ".svg": ("<!--", "-->"),
+    # CSS block comment
+    ".css": ("/*", "*/"),
+    ".scss": ("/*", "*/"),
+    ".less": ("/*", "*/"),
+}
+
+# Extensionless files keyed by name. Looked up only when `extension` is empty
+# or unknown.
+FILENAME_STYLES: dict[str, CommentStyle] = {
+    "Makefile": ("#", None),
+    "Dockerfile": ("#", None),
+    "Rakefile": ("#", None),
+    "Gemfile": ("#", None),
+    ".gitignore": ("#", None),
+    ".gitattributes": ("#", None),
+    ".dockerignore": ("#", None),
+    ".env": ("#", None),
+    ".notears": ("#", None),
+}
+
+
+def apply_hook(
+    content: str,
+    *,
+    max_tear: int = 3,
+    extension: str = ".py",
+    filename: str = "",
+) -> str:
+    """Return `content` with the `@tear` header rewritten to `max_tear`.
+
+    Two steps:
+    1. **Replacement (universal).** Scan the first 5 lines for any `@tear: <digit>`
+       in a comment-like position. Replace each digit with `max_tear`. Preserves
+       indentation, comment markers, trailing tokens (`-->`, `*/`), and line
+       endings.
+    2. **Insertion (type-specific).** If no header was found AND we know the
+       comment syntax for the file (looked up by `extension` then `filename`),
+       insert a new header. Insertion respects shebangs always; PEP 263 encoding
+       declarations are also respected (universally — they look like `# coding:
+       utf-8` and similar magic-comment patterns exist outside Python too).
+    """
+    lines = content.splitlines(keepends=True)
+
+    replaced = False
+    for i, line in enumerate(lines[:MAX_LINES]):
+        new_line, n = LINE_HEADER_RE.subn(rf"\g<1>{max_tear}", line, count=1)
+        if n:
+            lines[i] = new_line
+            replaced = True
+
+    if replaced:
+        return "".join(lines)
+
+    style = _resolve_style(extension, filename)
+    if style is None:
+        return content
+
+    insert_at = 0
+    if lines and SHEBANG_RE.match(lines[0]):
+        insert_at = 1
+    if insert_at < len(lines) and ENCODING_RE.search(lines[insert_at]):
+        insert_at += 1
+
+    ending = _detect_line_ending(lines)
+    lines.insert(insert_at, _format_header(style, max_tear) + ending)
+    return "".join(lines)
+
+
+def _resolve_style(extension: str, filename: str) -> CommentStyle | None:
+    """Look up the comment style for a file. Extension wins; filename is a
+    fallback for extensionless files (Makefile, Dockerfile, .gitignore)."""
+    style = COMMENT_STYLES.get(extension.lower())
+    if style is not None:
+        return style
+    return FILENAME_STYLES.get(filename)
+
+
+def _format_header(style: CommentStyle, max_tear: int) -> str:
+    """Render an `@tear: N` header in the appropriate comment style."""
+    opener, closer = style
+    if closer is None:
+        return f"{opener} @tear: {max_tear}"
+    return f"{opener} @tear: {max_tear} {closer}"
+
+
+def process_file(
+    path: Path,
+    *,
+    max_tear: int,
+    exclude: list[str],
+    repo_root: Path,
+) -> bool:
+    """Apply the hook to a single file. Returns True iff the file was modified.
+
+    Excluded paths and missing files are silently skipped. The decision about
+    *what* to do with the file (replace / insert / no-op) lives in `apply_hook`.
+    """
+    if not path.is_file():
+        return False
+    if is_excluded(path, repo_root, exclude):
+        return False
+    content = path.read_text()
+    new_content = apply_hook(
+        content, max_tear=max_tear, extension=path.suffix, filename=path.name
+    )
+    if new_content == content:
+        return False
+    path.write_text(new_content)
+    return True
+
+
+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:
+        # Broken config shouldn't break Claude Code. Fall back to defaults.
+        config = TearsConfig()
+
+    for path in paths:
+        try:
+            process_file(
+                path,
+                max_tear=config.max_tear,
+                exclude=config.exclude,
+                repo_root=repo_root,
+            )
+        except OSError:
+            continue
+    return 0
+
+
+def _detect_line_ending(lines: list[str]) -> str:
+    for line in lines:
+        if line.endswith("\r\n"):
+            return "\r\n"
+        if line.endswith("\n"):
+            return "\n"
+    return "\n"
+
+
+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 []
+
+
+def _find_repo_root(start: Path) -> Path:
+    """Walk up from `start` for the repo root. Fall back to cwd.
+
+    `.git/` wins over `.tears.toml` because nested configs exist legitimately
+    (test fixtures, monorepo subprojects). The canonical repo marker is `.git/`.
+    Only fall back to `.tears.toml` for repos that haven't been git-init'd yet.
+    """
+    here = start.resolve()
+    if here.is_file():
+        here = here.parent
+    ancestors = (here, *here.parents)
+    for ancestor in ancestors:
+        if (ancestor / ".git").exists():
+            return ancestor
+    for ancestor in ancestors:
+        if (ancestor / ".tears.toml").exists():
+            return ancestor
+    return Path.cwd()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tears_cli-0.1.0a1/src/tears/rules.py

@@ -0,0 +1,52 @@
+# @tear: 3
+"""Pure rule functions: tier comparison and directory requirements.
+
+These functions know nothing about files, imports, or graphs — they take primitive
+inputs and return booleans. The checker composes them.
+"""
+
+from __future__ import annotations
+
+
+def can_import(
+    importer_tier: int,
+    target_tier: int,
+    resolved_rules: dict[int, frozenset[int]],
+) -> bool:
+    """Is `importer_tier` allowed to import from `target_tier`?
+
+    `resolved_rules` is the pre-computed full matrix from
+    `TearsConfig.resolved_import_rules()`. Per-edge check is one set membership.
+    """
+    return target_tier in resolved_rules[importer_tier]
+
+
+def check_directory_requirement(
+    file_path: str,
+    file_tier: int,
+    requirements: dict[str, int],
+) -> bool:
+    """Does `file_tier` satisfy the longest-prefix-matching directory requirement?
+
+    Matching is path-segment aware: `src/auth` matches `src/auth/tokens.py` but NOT
+    `src/authentic/foo.py`. Files in unrestricted directories pass.
+    """
+    file_segments = _segments(file_path)
+    longest_match: int | None = None
+    longest_len = -1
+    for dir_key, required_tier in requirements.items():
+        dir_segments = _segments(dir_key)
+        if len(dir_segments) > len(file_segments):
+            continue
+        if file_segments[: len(dir_segments)] != dir_segments:
+            continue
+        if len(dir_segments) > longest_len:
+            longest_len = len(dir_segments)
+            longest_match = required_tier
+    if longest_match is None:
+        return True
+    return file_tier <= longest_match
+
+
+def _segments(path: str) -> tuple[str, ...]:
+    return tuple(p for p in path.strip("/").split("/") if p)

tears_cli-0.1.0a1/src/tears/scan.py

@@ -0,0 +1,65 @@
+# @tear: 3
+"""Scan orchestration and output formatting.
+
+Loads the config, builds the import graph via grimp, runs the checker, prints a
+human-readable report. The exact output format here is pinned by snapshot tests
+in `tests/scan/fixtures/`.
+"""
+
+from __future__ import annotations
+
+from io import StringIO
+from pathlib import Path
+
+from tears.checker import CheckReport, FileReport, check
+from tears.config import load_config
+from tears.graph.grimp_builder import build_grimp_graph
+
+
+def run_scan(repo_root: Path) -> tuple[CheckReport, str]:
+    """Run a full scan of `repo_root`. Returns the report and formatted output."""
+    config = load_config(repo_root)
+    graph = build_grimp_graph(repo_root, config)
+    report = check(graph, config, repo_root=repo_root)
+    return report, format_report(report, repo_root=repo_root)
+
+
+def format_report(report: CheckReport, *, repo_root: Path) -> str:
+    """Format a `CheckReport` for human consumption."""
+    out = StringIO()
+    for fr in report.files:
+        out.write(_format_file(fr, repo_root=repo_root))
+    out.write(_format_summary(report))
+    return out.getvalue()
+
+
+def _format_file(fr: FileReport, *, repo_root: Path) -> str:
+    label = {"ok": "OK   ", "warn": "WARN ", "fail": "FAIL "}[fr.status]
+    rel = _relative(fr.path, repo_root)
+    tier_suffix = f" (tear {fr.tier})" if fr.tier is not None else ""
+    line = f"{label} {rel}{tier_suffix}\n"
+    issues = "".join(f"  - {i.message}\n" for i in fr.issues)
+    suffix = "\n" if fr.issues else ""
+    return line + issues + suffix
+
+
+def _format_summary(report: CheckReport) -> str:
+    n = len(report.files)
+    failures = report.failure_count
+    warnings = report.warning_count
+    return (
+        f"{n} {_plural(n, 'file', 'files')} checked, "
+        f"{failures} {_plural(failures, 'failure', 'failures')}, "
+        f"{warnings} {_plural(warnings, 'warning', 'warnings')}\n"
+    )
+
+
+def _plural(n: int, singular: str, plural: str) -> str:
+    return singular if n == 1 else plural
+
+
+def _relative(path: Path, root: Path) -> str:
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return path.as_posix()