tears-cli 0.1.0__py3-none-any.whl

tears/mutate.py

@@ -0,0 +1,124 @@
+# @tear: 3
+"""Core tear-mutation primitives shared by the hook and CLI subcommands.
+
+`set_tear` sets a @tear header to an arbitrary level (replacing an existing one
+or inserting a new one). `process_file` is the filesystem boundary. `find_repo_root`
+locates the nearest .git dir or .tears.toml.
+
+The hook always calls process_file with tear=max_tear. The CLI subcommands
+`tears up`, `tears down`, and `tears set` call it after validating direction.
+`tears init` calls set_tear directly (it already holds the file content).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from tears.exclude import is_excluded
+from tears.styles import (
+    COMMENT_STYLES,
+    ENCODING_RE,
+    FILENAME_STYLES,
+    LINE_HEADER_RE,
+    MAX_HEADER_LINES,
+    SHEBANG_RE,
+    CommentStyle,
+)
+
+
+def set_tear(
+    content: str,
+    *,
+    tear: int = 3,
+    extension: str = ".py",
+    filename: str = "",
+) -> str:
+    """Return `content` with the @tear header set to `tear`.
+
+    Replaces any existing @tear line in the first 5 lines. If none is found and
+    the file type is known (by extension or filename), inserts a new header
+    respecting shebangs and PEP 263 encoding declarations.
+    """
+    lines = content.splitlines(keepends=True)
+
+    replaced = False
+    for i, line in enumerate(lines[:MAX_HEADER_LINES]):
+        new_line, n = LINE_HEADER_RE.subn(rf"\g<1>{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, tear) + ending)
+    return "".join(lines)
+
+
+def process_file(
+    path: Path,
+    *,
+    tear: int,
+    exclude: list[str],
+    repo_root: Path,
+) -> bool:
+    """Apply `set_tear` to a single file. Returns True iff the file was modified."""
+    if not path.is_file():
+        return False
+    if is_excluded(path, repo_root, exclude):
+        return False
+    content = path.read_text()
+    new_content = set_tear(content, tear=tear, extension=path.suffix, filename=path.name)
+    if new_content == content:
+        return False
+    path.write_text(new_content)
+    return True
+
+
+def find_repo_root(start: Path) -> Path:
+    """Walk up from `start` to find the repo root (.git dir wins, then .tears.toml)."""
+    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()
+
+
+def _resolve_style(extension: str, filename: str) -> CommentStyle | None:
+    style = COMMENT_STYLES.get(extension.lower())
+    if style is not None:
+        return style
+    return FILENAME_STYLES.get(filename)
+
+
+def _format_header(style: CommentStyle, tear: int) -> str:
+    opener, closer = style
+    if closer is None:
+        return f"{opener} @tear: {tear}"
+    return f"{opener} @tear: {tear} {closer}"
+
+
+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"

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/scan.py

@@ -0,0 +1,83 @@
+# @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 dataclasses import replace
+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
+
+_ANSI = {
+    "ok": "\033[32m",
+    "warn": "\033[33m",
+    "fail": "\033[31m",
+    "reset": "\033[0m",
+}
+
+
+def run_scan(
+    repo_root: Path,
+    *,
+    color: bool = False,
+    default_tear: int | None = None,
+) -> tuple[CheckReport, str]:
+    """Run a full scan of `repo_root`. Returns the report and formatted output."""
+    config = load_config(repo_root)
+    if default_tear is not None:
+        config = replace(config, default_tear=default_tear)
+    graph = build_grimp_graph(repo_root, config)
+    report = check(graph, config, repo_root=repo_root)
+    return report, format_report(report, repo_root=repo_root, color=color)
+
+
+def format_report(report: CheckReport, *, repo_root: Path, color: bool = False) -> str:
+    """Format a `CheckReport` for human consumption."""
+    out = StringIO()
+    for fr in report.files:
+        out.write(_format_file(fr, repo_root=repo_root, color=color))
+    out.write(_format_summary(report))
+    return out.getvalue()
+
+
+def _format_file(fr: FileReport, *, repo_root: Path, color: bool = False) -> str:
+    label = {"ok": "OK   ", "warn": "WARN ", "fail": "FAIL "}[fr.status]
+    if color:
+        label = f"{_ANSI[fr.status]}{label}{_ANSI['reset']}"
+    rel = _relative(fr.path, repo_root)
+    show_tier = fr.tier is not None or fr.is_defaulted
+    tier_suffix = f" (tear {fr.effective_tier})" if show_tier 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()

tears/styles.py

@@ -0,0 +1,91 @@
+# @tear: 2
+"""Comment-style lookup tables for @tear header insertion.
+
+`COMMENT_STYLES` keys on file extension; `FILENAME_STYLES` keys on bare filename
+for extensionless files (Makefile, Dockerfile, etc.). Each value is
+`(opener, closer)` — `closer` is None for line comments, a string for block comments.
+"""
+
+from __future__ import annotations
+
+import re
+
+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_HEADER_LINES = 5
+
+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": ("/*", "*/"),
+}
+
+FILENAME_STYLES: dict[str, CommentStyle] = {
+    "Makefile": ("#", None),
+    "Dockerfile": ("#", None),
+    "Rakefile": ("#", None),
+    "Gemfile": ("#", None),
+    ".gitignore": ("#", None),
+    ".gitattributes": ("#", None),
+    ".dockerignore": ("#", None),
+    ".env": ("#", None),
+    ".notears": ("#", None),
+}

tears_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.3
+Name: tears-cli
+Version: 0.1.0
+Summary: Tiered Enforcement, Authorship Review System — vibe-code responsibly.
+Author: Hillel Twersky
+Author-email: Hillel Twersky <35217356+Thillel@users.noreply.github.com>
+License: MIT License
+         
+         Copyright (c) 2026 HillelT
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Requires-Dist: grimp>=3.4
+Requires-Python: >=3.11

tears_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+tears/__init__.py,sha256=jgPo5r8xynvu78EjGYFfiPXPxQ_xY5XhdEgYXwPh9lM,11
+tears/__main__.py,sha256=6nzjgYLoIrtot_o2FvWuKb6j6jo_rMGczVmiSEL3vEE,64
+tears/checker.py,sha256=ZPCEoSOPR3UPupWUI6ivD7dk529Ug2M7Y3oFA0dsVeM,4952
+tears/cli.py,sha256=GcvDwiqnwwY8DwbPHso0SQhQu7mEFMLgXm17QfLJfZE,10682
+tears/config.py,sha256=3zHwGe95ObqOXVN_1HH3FXvrpzxt_5IBL4X6cs6hxEA,9745
+tears/exclude.py,sha256=nkqvDESnkQhcIEAHw6zET2mW6ikHkVYDp_F6XusmG2I,1197
+tears/graph/__init__.py,sha256=RW5Mr-3bCmsCOchh-zLxdJvUMQE1br2oz2DLZ2Mdda0,1236
+tears/graph/grimp_builder.py,sha256=3pvBN19FI7tJV_oJCcmJYyEg_O20wHxlAAIjd9Z3RJs,4909
+tears/header.py,sha256=MGWFgAK-YbrEKnaD_BgT6KbFn4rfi-QMbXfAbXpgKN4,973
+tears/hook.py,sha256=_gfp_Qnp9jXiJFtuOyZaP63w64Jo0gwt5MuDFTGx_Ac,2636
+tears/mutate.py,sha256=9rlJTkv_jQ6Gsj33NHhpN8oyXNSeJjzg91Y5aCAnTjQ,3556
+tears/rules.py,sha256=3kwo91eepQYgBmbHNZEYdhXTttQcAPqqaG0eUdPe_fA,1693
+tears/scan.py,sha256=rcyFqRSrWQEzNez29BdBUQpT49G9XmZiDafbKeUGGxA,2693
+tears/styles.py,sha256=uZta1ScXHaUuLZARBuujgQwh0lxae2qY4EK_Vmg_Lsc,2457
+tears_cli-0.1.0.dist-info/WHEEL,sha256=fWriCkzqm-pffF5af4gJC9iI5FMFaJTuN9UxxxzOmdY,81
+tears_cli-0.1.0.dist-info/entry_points.txt,sha256=LQ_6hCwT5_mYfi1Tu3ad5F6YrSYuGYhhyVb7qkgaHyQ,42
+tears_cli-0.1.0.dist-info/METADATA,sha256=KAYxrwESRrFtBzwQcgytm3plHZuHxomomhKNmJyYZac,1533
+tears_cli-0.1.0.dist-info/RECORD,,

tears_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.14
+Root-Is-Purelib: true
+Tag: py3-none-any

tears_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+tears = tears.cli:main
+