becwright 0.1.0__py3-none-any.whl

becwright/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

becwright/bundle.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import re
+import subprocess
+import textwrap
+from pathlib import Path
+
+import yaml
+
+from .rules import Rule
+
+BUNDLE_VERSION = 1
+
+_BUILTIN = re.compile(r"^python3?\s+-m\s+becwright\.checks\.(\w+)(?:\s+(.*))?$")
+_PY_PATH = re.compile(r"[\w./-]+\.py")
+_ITEM_INDENT = re.compile(r"^([ \t]+)-\s", re.MULTILINE)
+_EMPTY_RULES = re.compile(r"^rules:[ \t]*(?:\[[ \t]*\]|\{[ \t]*\})[ \t]*$", re.MULTILINE)
+
+
+class BundleError(RuntimeError):
+    pass
+
+
+def _clean(value):
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, list):
+        return [v.strip() if isinstance(v, str) else v for v in value]
+    return value
+
+
+def _origin(root: Path) -> str:
+    res = subprocess.run(
+        ["git", "config", "--get", "remote.origin.url"],
+        cwd=root, capture_output=True, text=True,
+    )
+    return res.stdout.strip() or root.name
+
+
+def classify_check(command: str, root: Path) -> dict:
+    command = command.strip()
+    builtin = _BUILTIN.match(command)
+    if builtin:
+        out = {"kind": "builtin", "module": builtin.group(1)}
+        if builtin.group(2):
+            out["args"] = builtin.group(2).strip()
+        return out
+    for token in _PY_PATH.findall(command):
+        candidate = root / token
+        if candidate.is_file():
+            return {
+                "kind": "script",
+                "filename": Path(token).name,
+                "source": candidate.read_text(encoding="utf-8"),
+            }
+    return {"kind": "command", "command": command}
+
+
+def export_bec(rule: Rule, root: Path) -> str:
+    rule_fields: dict = {"id": rule.id}
+    if rule.intent:
+        rule_fields["intent"] = rule.intent
+    if rule.why_it_matters:
+        rule_fields["why_it_matters"] = rule.why_it_matters
+    if rule.rejected_alternatives:
+        rule_fields["rejected_alternatives"] = list(rule.rejected_alternatives)
+    rule_fields["paths"] = list(rule.paths)
+    rule_fields["severity"] = rule.severity
+
+    bundle = {
+        "becwright_bec": BUNDLE_VERSION,
+        "exported_from": _origin(root),
+        "rule": rule_fields,
+        "check": classify_check(rule.check, root),
+    }
+    return yaml.safe_dump(bundle, sort_keys=False, allow_unicode=True)
+
+
+def parse_bundle(text: str) -> dict:
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as e:
+        raise BundleError(f"The bundle is not valid YAML: {e}")
+    if not isinstance(data, dict):
+        raise BundleError("The bundle is empty or malformed.")
+    if data.get("becwright_bec") != BUNDLE_VERSION:
+        raise BundleError(
+            f"Unsupported bundle version: {data.get('becwright_bec')!r} "
+            f"(expected {BUNDLE_VERSION})."
+        )
+    rule = data.get("rule")
+    check = data.get("check")
+    if not isinstance(rule, dict) or "id" not in rule:
+        raise BundleError("The bundle has no valid rule (missing 'rule.id').")
+    if not isinstance(check, dict) or "kind" not in check:
+        raise BundleError("The bundle has no valid check (missing 'check.kind').")
+    required = {"builtin": ("module",), "script": ("filename", "source"), "command": ("command",)}
+    kind = check["kind"]
+    if kind not in required:
+        raise BundleError(f"Unknown check kind: {kind!r}.")
+    missing = [f for f in required[kind] if not check.get(f)]
+    if missing:
+        raise BundleError(f"The '{kind}' check is missing fields: {', '.join(missing)}.")
+    return data
+
+
+def materialize(bundle: dict, root: Path) -> dict:
+    check = bundle["check"]
+    kind = check.get("kind")
+    if kind == "builtin":
+        command = f"python3 -m becwright.checks.{check['module']}"
+        if check.get("args"):
+            command += f" {check['args']}"
+    elif kind == "script":
+        filename = Path(check["filename"]).name
+        dest = root / ".bec" / "checks" / filename
+        source = check["source"]
+        if dest.exists() and dest.read_text(encoding="utf-8") != source:
+            raise BundleError(
+                f"A different check already exists at {dest}. Not overwriting it; resolve by hand."
+            )
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(source, encoding="utf-8")
+        dest.chmod(0o755)
+        command = f"python3 .bec/checks/{filename}"
+    elif kind == "command":
+        command = check["command"]
+    else:
+        raise BundleError(f"Unknown check kind: {kind!r}")
+
+    rule = bundle["rule"]
+    out: dict = {"id": rule["id"]}
+    for key in ("intent", "why_it_matters", "rejected_alternatives"):
+        if rule.get(key):
+            out[key] = _clean(rule[key])
+    out["paths"] = rule.get("paths", [])
+    out["check"] = command
+    out["severity"] = rule.get("severity", "blocking")
+    return out
+
+
+def append_rule(rules_path: Path, rule_dict: dict) -> None:
+    dumped = yaml.safe_dump([rule_dict], sort_keys=False, allow_unicode=True)
+    if not rules_path.exists():
+        rules_path.parent.mkdir(parents=True, exist_ok=True)
+        rules_path.write_text("rules:\n" + textwrap.indent(dumped, "  "), encoding="utf-8")
+        return
+    # Normalize an empty inline list (`rules: []`) so block items can follow it.
+    text = _EMPTY_RULES.sub("rules:", rules_path.read_text(encoding="utf-8"), count=1)
+    if text and not text.endswith("\n"):
+        text += "\n"
+    if not re.search(r"^rules:", text, re.MULTILINE):
+        text += "rules:\n"
+    # Match the indentation the file already uses for list items.
+    existing = _ITEM_INDENT.search(text)
+    prefix = existing.group(1) if existing else "  "
+    rules_path.write_text(text + textwrap.indent(dumped, prefix), encoding="utf-8")

becwright/checks/dangerous_eval.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import re
+import sys
+
+PATTERN = re.compile(r"\b(?:eval|exec)\s*\(")
+
+
+def find_violations(paths: list[str]) -> list[tuple[str, int, str]]:
+    violations: list[tuple[str, int, str]] = []
+    for path in paths:
+        path = path.strip()
+        if not path:
+            continue
+        try:
+            with open(path, encoding="utf-8") as f:
+                for lineno, line in enumerate(f, start=1):
+                    if PATTERN.search(line):
+                        violations.append((path, lineno, line.strip()))
+        except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
+            continue
+    return violations
+
+
+def main() -> int:
+    violations = find_violations(sys.stdin.read().splitlines())
+    for path, lineno, line in violations:
+        print(f"  {path}:{lineno}")
+        print(f"      > {line}")
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

becwright/checks/debug_remnants.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import re
+import sys
+
+PATTERN = re.compile(
+    r"\bbreakpoint\s*\(|\b(?:i?pdb)\.set_trace\s*\(|\bimport\s+i?pdb\b"
+)
+
+
+def find_violations(paths: list[str]) -> list[tuple[str, int, str]]:
+    violations: list[tuple[str, int, str]] = []
+    for path in paths:
+        path = path.strip()
+        if not path:
+            continue
+        try:
+            with open(path, encoding="utf-8") as f:
+                for lineno, line in enumerate(f, start=1):
+                    if PATTERN.search(line):
+                        violations.append((path, lineno, line.strip()))
+        except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
+            continue
+    return violations
+
+
+def main() -> int:
+    violations = find_violations(sys.stdin.read().splitlines())
+    for path, lineno, line in violations:
+        print(f"  {path}:{lineno}")
+        print(f"      > {line}")
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

becwright/checks/forbid.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+
+
+def find_violations(paths: list[str], pattern: str, flags: int = 0) -> list[tuple[str, int, str]]:
+    rx = re.compile(pattern, flags)
+    violations: list[tuple[str, int, str]] = []
+    for path in paths:
+        path = path.strip()
+        if not path:
+            continue
+        try:
+            with open(path, encoding="utf-8") as f:
+                for lineno, line in enumerate(f, start=1):
+                    if rx.search(line):
+                        violations.append((path, lineno, line.strip()))
+        except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
+            continue
+    return violations
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="becwright.checks.forbid",
+        description="Fails if a regex pattern appears in the files.",
+    )
+    parser.add_argument("--pattern", required=True, help="forbidden regex")
+    parser.add_argument("--ignore-case", action="store_true", help="ignore case")
+    parser.add_argument("--message", default="", help="note to show if there are matches")
+    args = parser.parse_args(argv)
+
+    try:
+        violations = find_violations(
+            sys.stdin.read().splitlines(),
+            args.pattern,
+            re.IGNORECASE if args.ignore_case else 0,
+        )
+    except re.error as e:
+        print(f"invalid pattern: {e}", file=sys.stderr)
+        return 2
+
+    if args.message and violations:
+        print(f"  {args.message}")
+    for path, lineno, line in violations:
+        print(f"  {path}:{lineno}")
+        print(f"      > {line}")
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

becwright/checks/hardcoded_secrets.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import re
+import sys
+
+_AWS_KEY = r"AKIA[0-9A-Z]{16}"
+_PRIVATE_KEY = r"-----BEGIN [A-Z ]*PRIVATE KEY-----"
+_ASSIGNMENT = (
+    r"(password|passwd|secret|api[_-]?key|token|access[_-]?key)"
+    r"\s*[:=]\s*['\"][^'\"]{6,}['\"]"
+)
+PATTERN = re.compile("|".join((_AWS_KEY, _PRIVATE_KEY, _ASSIGNMENT)), re.IGNORECASE)
+
+# Lines whose value reads as a placeholder, not a real secret.
+_PLACEHOLDER = re.compile(
+    r"os\.environ|getenv|<[^>]*>|\*{3,}|changeme|example|your[_-]|placeholder|dummy|xxxx",
+    re.IGNORECASE,
+)
+
+
+def find_violations(paths: list[str]) -> list[tuple[str, int, str]]:
+    violations: list[tuple[str, int, str]] = []
+    for path in paths:
+        path = path.strip()
+        if not path:
+            continue
+        try:
+            with open(path, encoding="utf-8") as f:
+                for lineno, line in enumerate(f, start=1):
+                    if PATTERN.search(line) and not _PLACEHOLDER.search(line):
+                        violations.append((path, lineno, line.strip()))
+        except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
+            continue
+    return violations
+
+
+def main() -> int:
+    violations = find_violations(sys.stdin.read().splitlines())
+    for path, lineno, line in violations:
+        print(f"  {path}:{lineno}")
+        print(f"      > {line}")
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

becwright/checks/no_token_in_logs.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import re
+import sys
+
+SENSITIVE = r"(token|password|passwd|secret|api[_-]?key|credential|session[_-]?id)"
+LOG_CALL = r"(log\.|logger\.|logging\.|print\s*\()"
+# A log call that mentions something sensitive on the same line.
+PATTERN = re.compile(LOG_CALL + r"[^\n]*" + SENSITIVE, re.IGNORECASE)
+
+
+def find_violations(paths: list[str]) -> list[tuple[str, int, str]]:
+    violations: list[tuple[str, int, str]] = []
+    for path in paths:
+        path = path.strip()
+        if not path:
+            continue
+        try:
+            with open(path, encoding="utf-8") as f:
+                for lineno, line in enumerate(f, start=1):
+                    if PATTERN.search(line):
+                        violations.append((path, lineno, line.strip()))
+        except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
+            continue
+    return violations
+
+
+def main() -> int:
+    violations = find_violations(sys.stdin.read().splitlines())
+    for path, lineno, line in violations:
+        print(f"  {path}:{lineno}")
+        print(f"      > {line}")
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

becwright/checks/redundant_comments.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import io
+import re
+import sys
+import tokenize
+
+# Short filler words that carry no meaning for the redundancy comparison.
+_STOP = {
+    "the", "and", "for", "with", "from", "this", "that", "here", "then", "when",
+    "each", "only", "not", "but", "its", "was", "are", "use", "via", "into",
+}
+# Pragmas and machine-readable comments are never style violations.
+_PRAGMA = ("type:", "noqa", "pragma", "pylint", "mypy", "ruff", "fmt:", "isort:")
+
+_WORDS = re.compile(r"[A-Za-z]+")
+
+
+def _significant(text: str) -> tuple[list[str], list[str]]:
+    words = _WORDS.findall(text.lower())
+    return words, [w for w in words if len(w) >= 3 and w not in _STOP]
+
+
+def _is_redundant(comment_text: str, code_line: str) -> bool:
+    body = comment_text.lstrip("#").strip()
+    if not body or body.startswith(_PRAGMA):
+        return False
+    words, significant = _significant(body)
+    # Long comments are prose (the "why"); only short labels can be restatements.
+    if not significant or len(words) > 6:
+        return False
+    code_words = set(_WORDS.findall(code_line.lower()))
+    return all(w in code_words for w in significant)
+
+
+def _next_code_line(lines: list[str], start_row: int) -> str:
+    for line in lines[start_row:]:
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#"):
+            return line
+    return ""
+
+
+def find_violations(paths: list[str]) -> list[tuple[str, int, str]]:
+    violations: list[tuple[str, int, str]] = []
+    for path in paths:
+        path = path.strip()
+        if not path:
+            continue
+        try:
+            text = open(path, encoding="utf-8").read()
+        except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
+            continue
+        lines = text.splitlines()
+        # tokenize so that `#` inside a string is never treated as a comment.
+        try:
+            tokens = list(tokenize.generate_tokens(io.StringIO(text).readline))
+        except (tokenize.TokenError, SyntaxError, IndentationError):
+            continue
+        for tok in tokens:
+            if tok.type != tokenize.COMMENT:
+                continue
+            row, col = tok.start
+            if row == 1 and tok.string.startswith("#!"):
+                continue
+            line = lines[row - 1]
+            before = line[:col]
+            code = before if before.strip() else _next_code_line(lines, row)
+            if code and _is_redundant(tok.string, code):
+                violations.append((path, row, tok.string.strip()))
+    return violations
+
+
+def main() -> int:
+    violations = find_violations(sys.stdin.read().splitlines())
+    for path, lineno, comment in violations:
+        print(f"  {path}:{lineno}")
+        print(f"      > {comment}")
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

becwright/checks/wildcard_imports.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import re
+import sys
+
+PATTERN = re.compile(r"^\s*from\s+[\w.]+\s+import\s+\*")
+
+
+def find_violations(paths: list[str]) -> list[tuple[str, int, str]]:
+    violations: list[tuple[str, int, str]] = []
+    for path in paths:
+        path = path.strip()
+        if not path:
+            continue
+        try:
+            with open(path, encoding="utf-8") as f:
+                for lineno, line in enumerate(f, start=1):
+                    if PATTERN.search(line):
+                        violations.append((path, lineno, line.strip()))
+        except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
+            continue
+    return violations
+
+
+def main() -> int:
+    violations = find_violations(sys.stdin.read().splitlines())
+    for path, lineno, line in violations:
+        print(f"  {path}:{lineno}")
+        print(f"      > {line}")
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

becwright/cli.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import argparse
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from . import __version__, bundle, git
+from .engine import Result, evaluate
+from .rules import load_rules
+
+RED = "\033[91m"; GREEN = "\033[92m"; YELLOW = "\033[93m"
+BOLD = "\033[1m"; DIM = "\033[2m"; RESET = "\033[0m"
+
+
+def _print_result(result: Result) -> None:
+    for r in result.per_rule:
+        if r.passed:
+            print(f"  {GREEN}PASS{RESET}  {r.rule.id}")
+            continue
+        if r.rule.is_blocking:
+            print(f"  {RED}{BOLD}BLOCK{RESET}  {r.rule.id}  {RED}(blocking){RESET}")
+        else:
+            print(f"  {YELLOW}WARN{RESET}  {r.rule.id}  {YELLOW}(warning only){RESET}")
+        if r.rule.intent:
+            print(f"        {DIM}Intent:{RESET} {r.rule.intent}")
+        if r.rule.why_it_matters:
+            print(f"        {DIM}Why it matters:{RESET} {r.rule.why_it_matters}")
+        if r.output:
+            print(f"        {DIM}Found in:{RESET}")
+            for line in r.output.splitlines():
+                print(f"        {line}")
+        print()
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    root = git.repo_root()
+    rules = load_rules(root / ".bec" / "rules.yaml")
+    if not rules:
+        print(f"{YELLOW}No .bec/rules.yaml with rules. Nothing to check.{RESET}")
+        return 0
+
+    files = git.files_to_check(root, all_files=args.all)
+    if not files:
+        print(f"{DIM}No files to check.{RESET}")
+        return 0
+
+    print(f"{BOLD}BEC -- {len(files)} file(s) against {len(rules)} rule(s){RESET}\n")
+    result = evaluate(rules, files, root)
+    _print_result(result)
+
+    if result.had_blocking:
+        print(f"{RED}{BOLD}>>> Commit BLOCKED: a blocking rule was broken.{RESET}")
+        print(f"{DIM}    Fix the above, or if it is intentional edit .bec/rules.yaml{RESET}")
+        return 1
+    print(f"{GREEN}{BOLD}>>> All good. Commit allowed.{RESET}")
+    return 0
+
+
+def _cmd_install(_: argparse.Namespace) -> int:
+    ok, msg = git.install_hook(git.repo_root())
+    print((GREEN if ok else YELLOW) + msg + RESET)
+    return 0
+
+
+def _cmd_uninstall(_: argparse.Namespace) -> int:
+    ok, msg = git.uninstall_hook(git.repo_root())
+    print((GREEN if ok else YELLOW) + msg + RESET)
+    return 0
+
+
+def _cmd_export(args: argparse.Namespace) -> int:
+    root = git.repo_root()
+    rule = next((r for r in load_rules(root / ".bec" / "rules.yaml") if r.id == args.rule_id), None)
+    if rule is None:
+        print(f"{RED}No rule with id '{args.rule_id}' in .bec/rules.yaml.{RESET}", file=sys.stderr)
+        return 1
+    text = bundle.export_bec(rule, root)
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+        print(f"{GREEN}BEC '{rule.id}' exported to {args.output}.{RESET}")
+    else:
+        sys.stdout.write(text)
+    return 0
+
+
+def _read_source(source: str) -> str:
+    if source.startswith(("http://", "https://")):
+        with urllib.request.urlopen(source, timeout=15) as resp:
+            return resp.read().decode("utf-8")
+    return Path(source).read_text(encoding="utf-8")
+
+
+def _print_bundle_summary(data: dict) -> None:
+    rule, check = data["rule"], data["check"]
+    print(f"{BOLD}BEC: {rule['id']}{RESET}  {DIM}(from {data.get('exported_from', '?')}){RESET}")
+    if rule.get("intent"):
+        print(f"  {DIM}Intent:{RESET} {rule['intent'].strip()}")
+    if rule.get("why_it_matters"):
+        print(f"  {DIM}Why it matters:{RESET} {rule['why_it_matters'].strip()}")
+    kind = check.get("kind")
+    print(f"  {DIM}Check:{RESET} {kind}")
+    if kind == "script":
+        print(f"  {DIM}Code of {check.get('filename')}:{RESET}")
+        for line in check.get("source", "").splitlines():
+            print(f"      {line}")
+    elif kind == "command":
+        print(f"  {DIM}Command:{RESET} {check.get('command')}")
+
+
+def _cmd_import(args: argparse.Namespace) -> int:
+    root = git.repo_root()
+    try:
+        data = bundle.parse_bundle(_read_source(args.source))
+    except (bundle.BundleError, OSError, urllib.error.URLError) as e:
+        print(f"{RED}Could not import: {e}{RESET}", file=sys.stderr)
+        return 1
+
+    _print_bundle_summary(data)
+    if not args.yes:
+        print(f"{YELLOW}Importing a BEC installs code that runs on every commit.{RESET}")
+        if input("Install this BEC? [y/N] ").strip().lower() not in ("y", "yes"):
+            print(f"{DIM}Cancelled. Nothing was written.{RESET}")
+            return 1
+
+    rules_path = root / ".bec" / "rules.yaml"
+    rule_id = data["rule"]["id"]
+    if rule_id in {r.id for r in load_rules(rules_path)}:
+        print(f"{RED}A rule with id '{rule_id}' already exists. Not duplicating it.{RESET}", file=sys.stderr)
+        return 1
+    try:
+        rule_dict = bundle.materialize(data, root)
+    except bundle.BundleError as e:
+        print(f"{RED}{e}{RESET}", file=sys.stderr)
+        return 1
+    bundle.append_rule(rules_path, rule_dict)
+    print(f"{GREEN}{BOLD}BEC '{rule_id}' installed in .bec/rules.yaml.{RESET}")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="becwright",
+        description="Enforces BECs (Bound Executable Constraints) on your code.",
+    )
+    parser.add_argument("--version", action="version", version=f"becwright {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_check = sub.add_parser("check", help="check the code against the rules")
+    p_check.add_argument("--all", action="store_true", help="check the whole repo, not just staging")
+    p_check.set_defaults(func=_cmd_check)
+
+    sub.add_parser("install", help="install the pre-commit hook").set_defaults(func=_cmd_install)
+    sub.add_parser("uninstall", help="remove the pre-commit hook").set_defaults(func=_cmd_uninstall)
+
+    p_export = sub.add_parser("export", help="export a BEC to a .bec.yaml file")
+    p_export.add_argument("rule_id", help="id of the rule to export")
+    p_export.add_argument("-o", "--output", help="output file (default: stdout)")
+    p_export.set_defaults(func=_cmd_export)
+
+    p_import = sub.add_parser("import", help="import a BEC from a file or URL")
+    p_import.add_argument("source", help="path to a .bec.yaml or http(s) URL")
+    p_import.add_argument("--yes", action="store_true", help="install without asking for confirmation")
+    p_import.set_defaults(func=_cmd_import)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except git.NotAGitRepo as e:
+        print(f"{RED}{e}{RESET}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

becwright/engine.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .rules import Rule
+
+
+def _glob_to_regex(pattern: str) -> str:
+    # `**/` = zero or more dirs; `**` = anything; `*` = anything but `/`.
+    i = 0
+    out: list[str] = []
+    while i < len(pattern):
+        if pattern[i:i + 3] == "**/":
+            out.append("(?:.*/)?")
+            i += 3
+        elif pattern[i:i + 2] == "**":
+            out.append(".*")
+            i += 2
+        elif pattern[i] == "*":
+            out.append("[^/]*")
+            i += 1
+        elif pattern[i] == ".":
+            out.append(r"\.")
+            i += 1
+        else:
+            out.append(re.escape(pattern[i]))
+            i += 1
+    return "^" + "".join(out) + "$"
+
+
+def matches(path: str, patterns: tuple[str, ...]) -> bool:
+    return any(re.match(_glob_to_regex(p), path) for p in patterns)
+
+
+@dataclass(frozen=True)
+class RuleResult:
+    rule: Rule
+    passed: bool
+    output: str  # check stdout: the violations it found
+
+
+@dataclass(frozen=True)
+class Result:
+    per_rule: list[RuleResult]
+
+    @property
+    def had_blocking(self) -> bool:
+        return any(not r.passed and r.rule.is_blocking for r in self.per_rule)
+
+
+def evaluate(rules: list[Rule], files: list[str], root: Path) -> Result:
+    results: list[RuleResult] = []
+    for rule in rules:
+        relevant = [f for f in files if matches(f, rule.paths)]
+        if not relevant:
+            continue
+        proc = subprocess.run(
+            rule.check, shell=True, cwd=root,
+            input="\n".join(relevant), capture_output=True, text=True,
+        )
+        output = proc.stdout.strip() or proc.stderr.strip()
+        results.append(
+            RuleResult(rule=rule, passed=proc.returncode == 0, output=output)
+        )
+    return Result(per_rule=results)

becwright/git.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+# Marker used to recognize (and safely remove) a hook written by becwright.
+_HOOK_MARK = "# >>> becwright hook >>>"
+
+_HOOK_CONTENT = f"""#!/bin/sh
+{_HOOK_MARK}
+# Generated by `becwright install`. Do not edit by hand: use `becwright uninstall`.
+exec becwright check
+# <<< becwright hook <<<
+"""
+
+
+class NotAGitRepo(RuntimeError):
+    pass
+
+
+def repo_root() -> Path:
+    res = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        capture_output=True, text=True,
+    )
+    if res.returncode != 0:
+        raise NotAGitRepo("You are not inside a git repository.")
+    return Path(res.stdout.strip())
+
+
+def files_to_check(root: Path, *, all_files: bool) -> list[str]:
+    if all_files:
+        cmd = ["git", "ls-files"]
+    else:
+        cmd = ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM"]
+    res = subprocess.run(cmd, cwd=root, capture_output=True, text=True)
+    return [line for line in res.stdout.splitlines() if line.strip()]
+
+
+def _hook_path(root: Path) -> Path:
+    return root / ".git" / "hooks" / "pre-commit"
+
+
+def install_hook(root: Path) -> tuple[bool, str]:
+    hook = _hook_path(root)
+    if hook.exists():
+        content = hook.read_text(encoding="utf-8")
+        if _HOOK_MARK in content:
+            return False, "The becwright hook was already installed."
+        # Never clobber a pre-commit hook we did not write.
+        return False, (
+            f"A non-becwright pre-commit already exists at {hook}. "
+            "Leaving it; remove or integrate it by hand."
+        )
+    hook.parent.mkdir(parents=True, exist_ok=True)
+    hook.write_text(_HOOK_CONTENT, encoding="utf-8")
+    hook.chmod(0o755)
+    return True, f"Hook installed at {hook}."
+
+
+def uninstall_hook(root: Path) -> tuple[bool, str]:
+    hook = _hook_path(root)
+    if not hook.exists():
+        return False, "No pre-commit hook to remove."
+    if _HOOK_MARK not in hook.read_text(encoding="utf-8"):
+        return False, "The existing pre-commit is not becwright's; leaving it."
+    hook.unlink()
+    return True, "becwright hook uninstalled."

becwright/rules.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    paths: tuple[str, ...]
+    check: str
+    intent: str = ""
+    why_it_matters: str = ""
+    rejected_alternatives: tuple[str, ...] = ()
+    severity: str = "blocking"  # blocking = stops the commit | warning = only warns
+
+    @property
+    def is_blocking(self) -> bool:
+        return self.severity == "blocking"
+
+
+def _to_rule(raw: dict) -> Rule:
+    return Rule(
+        id=raw["id"],
+        paths=tuple(raw.get("paths", [])),
+        check=raw["check"],
+        intent=(raw.get("intent") or "").strip(),
+        why_it_matters=(raw.get("why_it_matters") or "").strip(),
+        rejected_alternatives=tuple(raw.get("rejected_alternatives", [])),
+        severity=raw.get("severity", "blocking"),
+    )
+
+
+def load_rules(rules_path: Path) -> list[Rule]:
+    if not rules_path.exists():
+        return []
+    data = yaml.safe_load(rules_path.read_text(encoding="utf-8")) or {}
+    return [_to_rule(r) for r in data.get("rules", [])]

becwright-0.1.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: becwright
+Version: 0.1.0
+Summary: Deterministically enforces constraints (BECs) on your code, blocking commits that violate them.
+Author: Alonso David De Leon Rodarte
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Dynamic: license-file
+
+> **English** · [Español](README.es.md)
+
+# becwright
+
+[![CI](https://github.com/DataDave-Dev/becwright/actions/workflows/ci.yml/badge.svg)](https://github.com/DataDave-Dev/becwright/actions/workflows/ci.yml)
+
+**Rules that run, not notes that get ignored.**
+
+`becwright` enforces constraints on your code deterministically: instead of
+*asking* an AI agent to respect a rule (the way `CLAUDE.md`, `.cursorrules`,
+etc. do — which the agent can read and ignore), becwright **verifies the
+result** and blocks the commit if the rule is broken.
+
+## The problem
+
+An AI agent writes code and leaves a note: *"this must never log session
+tokens"*. That note is text. Three months later, another agent regenerates the
+module, doesn't read it, and drops the token into the logs. Nobody notices
+until it blows up in production.
+
+Notes are **probabilistic** (they depend on the agent reading, understanding and
+obeying). becwright is **deterministic**: the rule runs against the real code
+and returns pass/fail, no matter which agent or model made the change.
+
+| | Note in CLAUDE.md | becwright rule |
+|---|---|---|
+| What it does | *Asks* to be respected | *Verifies* it was respected |
+| Depends on | The agent reading and obeying | Nothing — it runs against the code |
+| Result | Likely | Guaranteed |
+| Analogy | A "speed limit" sign | A physical bump in the road |
+
+The two layers are complementary: CLAUDE.md prevents (so 95% comes out right the
+first time), becwright is the safety net for the 5% that slips through.
+
+## Core concept: BEC (Bound Executable Constraint)
+
+A BEC is a constraint with three properties that no current artifact has
+together:
+
+- **Bound** — the rule is born tied to the *intent* and the decision that
+  created it (the *why*); it is not a loose rule without context.
+- **Executable** — it carries a check that runs and returns pass/fail; it is not
+  prose someone promises to respect.
+- **Portable** — it can be exported from one repo and imported into another,
+  like a package (this is what creates the network effect over time).
+
+## How to use it
+
+becwright is installed once as a tool; each repo only contributes its own
+`.bec/rules.yaml`.
+
+```bash
+# 1. Install the engine (once, global)
+pipx install git+https://github.com/DataDave-Dev/becwright.git   # or local: pipx install .
+
+# 2. In the repo where you want the rules, install the git hook
+becwright install                   # writes .git/hooks/pre-commit
+
+# 3. Write your rules in .bec/rules.yaml (see examples below)
+# 4. Done: each commit runs the checks; if a blocking rule fails, it stops.
+```
+
+Available commands:
+
+| Command | What it does |
+|---|---|
+| `becwright check` | Runs the rules over the staged files |
+| `becwright install` | Installs the native `pre-commit` hook |
+| `becwright uninstall` | Removes the hook |
+| `becwright export <id>` | Exports a BEC to a `.bec.yaml` file |
+| `becwright import <file\|URL>` | Imports a BEC from another repo |
+
+A rule in `.bec/rules.yaml`:
+
+```yaml
+rules:
+  - id: no-token-in-logs
+    intent: >
+      Session tokens and credentials must never reach any log.
+    why_it_matters: >
+      If a token shows up in the logs, anyone with access to them can steal a
+      user's session.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.no_token_in_logs"
+    severity: blocking   # blocking = stops the commit | warning = only warns
+```
+
+## Included checks
+
+becwright ships ready-to-use checks. Each one is a module invoked from the
+`check` field. They are **text/regex based** (no AST analysis), so they are
+conservative and may have edge cases; the value is in tying each rule to its
+*why*.
+
+| Check | What it detects | Language | Suggested severity |
+|---|---|---|---|
+| `forbid` | Any regex you pass (`--pattern`) | any | depends on the case |
+| `no_token_in_logs` | Tokens/credentials in log calls | Python | `blocking` |
+| `hardcoded_secrets` | AWS keys, private keys, `password = "..."` literals | any | `blocking` |
+| `debug_remnants` | Forgotten `breakpoint()`, `pdb.set_trace()`, `import pdb` | Python | `blocking` |
+| `dangerous_eval` | `eval()` / `exec()` calls | any | `blocking` |
+| `wildcard_imports` | `from x import *` | Python | `warning` |
+
+Example rules to copy into your `.bec/rules.yaml`:
+
+```yaml
+rules:
+  - id: no-hardcoded-secrets
+    intent: >
+      No secret (key, token, password) should be hardcoded in the code.
+    why_it_matters: >
+      A secret in the repo stays in git history forever and is visible to
+      anyone with access to the code.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.hardcoded_secrets"
+    severity: blocking
+
+  - id: no-debug-remnants
+    intent: >
+      Debug code (breakpoints, pdb) must not be committed.
+    why_it_matters: >
+      A forgotten breakpoint hangs the process in production or CI.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.debug_remnants"
+    severity: blocking
+
+  - id: no-dangerous-eval
+    intent: >
+      Do not use eval()/exec(), which execute arbitrary code.
+    why_it_matters: >
+      eval/exec on untrusted input is remote code execution.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.dangerous_eval"
+    severity: blocking
+
+  - id: no-wildcard-imports
+    intent: >
+      Avoid 'from x import *', which pollutes the namespace.
+    why_it_matters: >
+      Wildcard imports hide where each name comes from and break static
+      analysis.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.wildcard_imports"
+    severity: warning
+```
+
+## Any language
+
+becwright is **language-agnostic**: the engine only filters files by their
+`paths` (globs) and runs the `check` as a command; it never assumes Python. You
+can watch JavaScript, Go, Rust, or anything else.
+
+The fastest way to write a rule for another language —without writing code— is
+the `forbid` check, which fails if a regex appears in the files:
+
+```yaml
+rules:
+  - id: no-debugger-js
+    intent: >
+      Do not leave 'debugger;' in JavaScript/TypeScript code.
+    why_it_matters: >
+      A forgotten 'debugger' halts execution and should not reach production.
+    paths: ["**/*.js", "**/*.ts"]
+    check: "python3 -m becwright.checks.forbid --pattern '\\bdebugger\\b'"
+    severity: blocking
+```
+
+`forbid` accepts `--pattern REGEX`, `--ignore-case` and `--message TEXT`. For
+finer checks, write your own script in whatever language you want (an executable
+that reads the file list from stdin and exits with code 0/1) and point `check`
+at it.
+
+## Sharing BECs between repos
+
+A BEC is **portable**: you can take it out of one repo and install it in
+another. A bundle is a single self-contained `.bec.yaml` file (the rule + the
+check's code if it is custom).
+
+```bash
+# In the source repo: export a rule to a file
+becwright export no-token-in-logs -o no-token-in-logs.bec.yaml
+
+# In another repo: import it (from a file or an http/https URL)
+becwright import no-token-in-logs.bec.yaml
+becwright import https://example.com/no-token-in-logs.bec.yaml
+```
+
+On import, becwright **shows the check's code and asks for confirmation** before
+installing it: importing a BEC is importing code that will run on every commit.
+Use `--yes` to skip the confirmation in automated environments.
+
+There is a **catalog of ready-to-use BECs** in [`becs/`](becs/) that you can
+import directly from their raw URL.
+
+Built-in checks (`python3 -m becwright.checks.*`) travel with the package, so
+the bundle only stores their name. A **custom** check (`.bec/checks/foo.py`)
+travels with its code embedded and lands in `.bec/checks/` of the target repo.
+
+## Current status
+
+The **installable MVP** is built and verified end-to-end: packaged engine
+(`src/becwright/`), CLI (`check` / `install` / `uninstall` / `export` /
+`import`), native git hook that blocks a commit with a token in a log, included
+checks (Python + the generic `forbid` for any language), BEC portability between
+repos, a catalog with Python and JS/TS BECs, and a green test suite. The original
+prototype is **archived** under `prototype/` as a reference.
+
+Future work (AST analysis, deep per-language tooling, cryptographic signing of
+verifications) is documented in the project plan.

becwright-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+becwright/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+becwright/bundle.py,sha256=fMn7GXebJRIWen4urzqB0SyHaWXCOB9GjwBjCeJGJVY,5647
+becwright/cli.py,sha256=0Gp3j2CNnFIf0X3H3ovxN-MfMuqAcDjoFZuHfGt9EX4,6726
+becwright/engine.py,sha256=LMYzWsWoki28QUuSviGfHOGfEeaKLo4rnHuTCI8vn4g,1857
+becwright/git.py,sha256=ZwP27d3xfCSSXLGCtp5QWHv9nipkpUbyJ4uYFex8BiI,2149
+becwright/rules.py,sha256=PKxucBqtPem33F4HnMNl6X3MmkVRAqUVwPv-_WuwiIY,1096
+becwright/checks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+becwright/checks/dangerous_eval.py,sha256=XTLlaRLiYiRNxeJtk5ZlGGANbfTwpT8CrlLbOUYGR_c,955
+becwright/checks/debug_remnants.py,sha256=YxjdsVu8kAPJQGpME3HuDBJKdd59zMxILE-ePF5xZW4,1005
+becwright/checks/forbid.py,sha256=ghBW6O944t7i7IW-ZxJe1GhDoXDrbAtR3YD-zstmFV8,1740
+becwright/checks/hardcoded_secrets.py,sha256=euOSwAjPn_oTgRUVWu2bpH5BubOZ1gEEf9fNHMZ9G_A,1436
+becwright/checks/no_token_in_logs.py,sha256=2NdTOgAavVw-PwNvobJvxaSg6sABvhtt955rNGduisQ,1180
+becwright/checks/redundant_comments.py,sha256=vhX-BRkCRQMVD39fuXEzKwEKHJr19QR7LOaDMjOjtOA,2840
+becwright/checks/wildcard_imports.py,sha256=6r7Qo6886we3hNkFgCL7ASZvGw5GfAkDy1rVswK34Mo,966
+becwright-0.1.0.dist-info/licenses/LICENSE,sha256=l2gLf5s0NiJqhdVyb4E5VYxpZa6XXy7urnLrIzQX8OA,1085
+becwright-0.1.0.dist-info/METADATA,sha256=ImLKGgQZ3d3a_88HDxRiVJFfp-AvtGRr6QzZLf2wUIM,8982
+becwright-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+becwright-0.1.0.dist-info/entry_points.txt,sha256=1dYz-6H3O9WKYazgU9rfICc9j3GDIXDXApSG62TlvQo,49
+becwright-0.1.0.dist-info/top_level.txt,sha256=11x6Cfccs-MD8MkICxo8TXicjXgpyYouw6y4bTp1uZA,10
+becwright-0.1.0.dist-info/RECORD,,

becwright-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

becwright-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+becwright = becwright.cli:main

becwright-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alonso David De Leon Rodarte
+
+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.

becwright-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+becwright