claude-dev-env 1.34.1 → 1.36.0

package/skills/bugteam/scripts/bugteam_code_rules_gate.py

@@ -1,633 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import ast
-import importlib.util
-import re
-import subprocess
-import sys
-from pathlib import Path
-
-
-def hunk_header_pattern() -> re.Pattern[str]:
-    return re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")
-
-
-def violation_line_pattern() -> re.Pattern[str]:
-    return re.compile(r"^Line (\d+):")
-
-
-def resolve_claude_dev_env_root() -> Path:
-    environment_value = (Path(__file__).resolve().parents[3]).resolve()
-    return environment_value
-
-
-def load_validate_content():
-    package_root = resolve_claude_dev_env_root()
-    enforcer_path = package_root / "hooks" / "blocking" / "code_rules_enforcer.py"
-    if not enforcer_path.is_file():
-        message = f"bugteam_code_rules_gate: missing enforcer at {enforcer_path}"
-        print(message, file=sys.stderr)
-        raise SystemExit(2)
-    specification = importlib.util.spec_from_file_location(
-        "code_rules_enforcer",
-        enforcer_path,
-    )
-    if specification is None or specification.loader is None:
-        print("bugteam_code_rules_gate: could not load code_rules_enforcer.", file=sys.stderr)
-        raise SystemExit(2)
-    module = importlib.util.module_from_spec(specification)
-    specification.loader.exec_module(module)
-    return module.validate_content
-
-
-def resolve_merge_base(repository_root: Path, base_reference: str) -> str:
-    merge_result = subprocess.run(
-        ["git", "merge-base", "HEAD", base_reference],
-        cwd=str(repository_root),
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        check=False,
-    )
-    if merge_result.returncode != 0:
-        print(
-            f"bugteam_code_rules_gate: git merge-base HEAD {base_reference} failed:\n"
-            f"{merge_result.stderr}",
-            file=sys.stderr,
-        )
-        raise SystemExit(2)
-    return merge_result.stdout.strip()
-
-
-def filter_paths_under_prefixes(
-    file_paths: list[Path],
-    repository_root: Path,
-    prefix_list: list[str],
-) -> list[Path]:
-    if not prefix_list:
-        return file_paths
-    normalized_prefixes = [
-        each.strip().replace("\\", "/").rstrip("/")
-        for each in prefix_list
-        if each.strip()
-    ]
-    if not normalized_prefixes:
-        return file_paths
-    resolved_root = repository_root.resolve()
-    filtered: list[Path] = []
-    for each_path in file_paths:
-        try:
-            relative_posix = each_path.resolve().relative_to(resolved_root).as_posix()
-        except ValueError:
-            continue
-        if any(
-            relative_posix == prefix or relative_posix.startswith(prefix + "/")
-            for prefix in normalized_prefixes
-        ):
-            filtered.append(each_path)
-    return filtered
-
-
-def paths_from_git_staged(repository_root: Path) -> list[Path]:
-    name_result = subprocess.run(
-        ["git", "diff", "--cached", "--name-only", "-z"],
-        cwd=str(repository_root),
-        capture_output=True,
-        check=False,
-    )
-    if name_result.returncode != 0:
-        stderr_text = name_result.stderr.decode("utf-8", errors="replace")
-        print(
-            f"bugteam_code_rules_gate: git diff --cached --name-only -z failed:\n{stderr_text}",
-            file=sys.stderr,
-        )
-        raise SystemExit(2)
-    raw_paths = name_result.stdout.split(b"\x00")
-    resolved_paths = []
-    for each_raw_path in raw_paths:
-        if not each_raw_path:
-            continue
-        try:
-            relative_path = each_raw_path.decode("utf-8")
-        except UnicodeDecodeError:
-            print(
-                f"bugteam_code_rules_gate: skipping staged path with non-UTF-8 filename: {each_raw_path!r}",
-                file=sys.stderr,
-            )
-            continue
-        resolved_paths.append(repository_root / relative_path)
-    return resolved_paths
-
-
-def staged_file_line_count(
-    repository_root: Path,
-    relative_path_posix: str,
-) -> int:
-    show_result = subprocess.run(
-        ["git", "show", f":{relative_path_posix}"],
-        cwd=str(repository_root),
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        check=False,
-    )
-    if show_result.returncode != 0:
-        return 0
-    staged_content = show_result.stdout
-    if not staged_content:
-        return 0
-    return len(staged_content.splitlines())
-
-
-def is_staged_file_newly_added(
-    repository_root: Path,
-    relative_path_posix: str,
-) -> bool:
-    status_result = subprocess.run(
-        ["git", "diff", "--cached", "--name-status", "--", relative_path_posix],
-        cwd=str(repository_root),
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        check=False,
-    )
-    if status_result.returncode != 0:
-        return False
-    for each_line in status_result.stdout.splitlines():
-        stripped_line = each_line.strip()
-        if stripped_line:
-            return stripped_line.startswith("A")
-    return False
-
-
-def added_lines_for_staged_file(
-    repository_root: Path,
-    relative_path_posix: str,
-) -> set[int]:
-    diff_result = subprocess.run(
-        ["git", "diff", "--cached", "--unified=0", "--", relative_path_posix],
-        cwd=str(repository_root),
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        check=False,
-    )
-    if diff_result.returncode != 0:
-        print(
-            f"bugteam_code_rules_gate: git diff --cached --unified=0 failed for {relative_path_posix}:\n"
-            f"{diff_result.stderr}",
-            file=sys.stderr,
-        )
-        raise SystemExit(2)
-    if diff_result.stdout.strip():
-        return parse_added_line_numbers(diff_result.stdout)
-    if is_staged_file_newly_added(repository_root, relative_path_posix):
-        total_lines = staged_file_line_count(repository_root, relative_path_posix)
-        if total_lines > 0:
-            return set(range(1, total_lines + 1))
-    return set()
-
-
-def added_lines_by_file_staged(
-    repository_root: Path,
-    file_paths: list[Path],
-) -> dict[Path, set[int]]:
-    resolved_root = repository_root.resolve()
-    added_by_path: dict[Path, set[int]] = {}
-    for each_path in file_paths:
-        try:
-            resolved = each_path.resolve()
-        except OSError:
-            continue
-        try:
-            relative = resolved.relative_to(resolved_root)
-        except ValueError:
-            continue
-        relative_posix = str(relative).replace("\\", "/")
-        added_numbers = added_lines_for_staged_file(resolved_root, relative_posix)
-        added_by_path[resolved] = added_numbers
-    return added_by_path
-
-
-def paths_from_git_diff(repository_root: Path, base_reference: str) -> list[Path]:
-    merge_base = resolve_merge_base(repository_root, base_reference)
-    name_result = subprocess.run(
-        ["git", "diff", "--name-only", f"{merge_base}..HEAD"],
-        cwd=str(repository_root),
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        check=False,
-    )
-    if name_result.returncode != 0:
-        print(
-            f"bugteam_code_rules_gate: git diff --name-only failed:\n{name_result.stderr}",
-            file=sys.stderr,
-        )
-        raise SystemExit(2)
-    relative_paths = [line.strip() for line in name_result.stdout.splitlines() if line.strip()]
-    return [repository_root / relative_path for relative_path in relative_paths]
-
-
-def is_code_path(file_path: Path) -> bool:
-    suffix = file_path.suffix.lower()
-    return suffix in {".py", ".js", ".ts", ".tsx", ".jsx"}
-
-
-def check_database_column_string_magic(content: str, file_path: str) -> list[str]:
-    """Flag string literals that look like database/HTTP column or key names inside function bodies.
-
-    Triggers when a snake_case string literal appears as the first element of a
-    two-element tuple inside a function body (the characteristic column-name/value
-    pair pattern). Files under ``config/`` and test files are exempt.
-    """
-    if "/config/" in file_path.replace("\\", "/") or "\\config\\" in file_path:
-        return []
-    if "/tests/" in file_path.replace("\\", "/") or file_path.endswith(("_test.py", ".spec.py")):
-        return []
-    try:
-        tree = ast.parse(content)
-    except SyntaxError:
-        return []
-    issues: list[str] = []
-    column_key_pattern = re.compile(r"^[a-z][a-z0-9_]{2,}$")
-    for node in ast.walk(tree):
-        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            continue
-        for each_child in ast.walk(node):
-            if not isinstance(each_child, ast.Tuple):
-                continue
-            if len(each_child.elts) != 2:
-                continue
-            first_element = each_child.elts[0]
-            if not isinstance(first_element, ast.Constant):
-                continue
-            if not isinstance(first_element.value, str):
-                continue
-            literal_text = first_element.value
-            if not column_key_pattern.match(literal_text):
-                continue
-            if literal_text in {"true", "false", "none", "null"}:
-                continue
-            issues.append(
-                f"Line {first_element.lineno}: Column-name string magic {literal_text!r} - extract to config"
-            )
-            if len(issues) >= 3:
-                return issues
-    return issues
-
-
-def check_wrapper_plumb_through(content: str, file_path: str) -> list[str]:
-    """Flag public wrappers that drop optional kwargs of a same-file delegate.
-
-    Walks the AST. For every public function (name does not start with '_'),
-    if its body contains exactly one direct call to another same-file
-    function and that delegate's signature accepts optional kwargs that the
-    wrapper does not also accept, emit a finding with both line numbers.
-    """
-    if file_path.endswith((".js", ".ts", ".tsx", ".jsx")):
-        return []
-    try:
-        tree = ast.parse(content)
-    except SyntaxError:
-        return []
-    function_signatures: dict[str, set[str]] = {}
-    for node in ast.walk(tree):
-        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            optional_kwargs: set[str] = set()
-            for each_kwonly, each_default in zip(node.args.kwonlyargs, node.args.kw_defaults):
-                if each_default is not None:
-                    optional_kwargs.add(each_kwonly.arg)
-            function_signatures[node.name] = optional_kwargs
-    issues: list[str] = []
-    for node in ast.walk(tree):
-        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            continue
-        if node.name.startswith("_"):
-            continue
-        wrapper_kwargs = function_signatures.get(node.name, set())
-        for each_call in ast.walk(node):
-            if not isinstance(each_call, ast.Call):
-                continue
-            if not isinstance(each_call.func, ast.Attribute):
-                continue
-            delegate_name = each_call.func.attr
-            delegate_kwargs = function_signatures.get(delegate_name)
-            if delegate_kwargs is None:
-                continue
-            missing = delegate_kwargs - wrapper_kwargs
-            if missing:
-                issues.append(
-                    f"Line {node.lineno}: Wrapper {node.name!r} drops optional kwargs {sorted(missing)!r} of delegate {delegate_name!r}"
-                )
-                if len(issues) >= 3:
-                    return issues
-    return issues
-
-
-def parse_added_line_numbers(unified_diff_text: str) -> set[int]:
-    header_regex = hunk_header_pattern()
-    added_line_numbers: set[int] = set()
-    for each_line in unified_diff_text.splitlines():
-        header_match = header_regex.match(each_line)
-        if header_match is None:
-            continue
-        new_start_text, new_count_text = header_match.groups()
-        new_start = int(new_start_text)
-        new_count = 1 if new_count_text is None else int(new_count_text)
-        if new_count <= 0:
-            continue
-        for each_number in range(new_start, new_start + new_count):
-            added_line_numbers.add(each_number)
-    return added_line_numbers
-
-
-def is_file_new_at_base(
-    repository_root: Path,
-    merge_base: str,
-    relative_path_posix: str,
-) -> bool:
-    cat_result = subprocess.run(
-        ["git", "cat-file", "-e", f"{merge_base}:{relative_path_posix}"],
-        cwd=str(repository_root),
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        check=False,
-    )
-    return cat_result.returncode != 0
-
-
-def added_lines_for_file(
-    repository_root: Path,
-    merge_base: str,
-    relative_path_posix: str,
-) -> set[int]:
-    diff_result = subprocess.run(
-        ["git", "diff", "--unified=0", f"{merge_base}..HEAD", "--", relative_path_posix],
-        cwd=str(repository_root),
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        check=False,
-    )
-    if diff_result.returncode != 0:
-        print(
-            f"bugteam_code_rules_gate: git diff --unified=0 failed for {relative_path_posix}:\n"
-            f"{diff_result.stderr}",
-            file=sys.stderr,
-        )
-        raise SystemExit(2)
-    if not diff_result.stdout.strip():
-        return set()
-    return parse_added_line_numbers(diff_result.stdout)
-
-
-def whole_file_line_set(file_path: Path) -> set[int]:
-    try:
-        total_lines = len(file_path.read_text().splitlines())
-    except OSError:
-        return set()
-    if total_lines <= 0:
-        return set()
-    return set(range(1, total_lines + 1))
-
-
-def added_lines_by_file(
-    repository_root: Path,
-    base_reference: str,
-    file_paths: list[Path],
-) -> dict[Path, set[int]]:
-    merge_base = resolve_merge_base(repository_root, base_reference)
-    resolved_root = repository_root.resolve()
-    added_by_path: dict[Path, set[int]] = {}
-    for each_path in file_paths:
-        try:
-            resolved = each_path.resolve()
-        except OSError:
-            continue
-        try:
-            relative = resolved.relative_to(resolved_root)
-        except ValueError:
-            continue
-        relative_posix = str(relative).replace("\\", "/")
-        added_numbers = added_lines_for_file(resolved_root, merge_base, relative_posix)
-        if not added_numbers and resolved.is_file():
-            if is_file_new_at_base(resolved_root, merge_base, relative_posix):
-                added_numbers = whole_file_line_set(resolved)
-        added_by_path[resolved] = added_numbers
-    return added_by_path
-
-
-def extract_violation_line_number(violation_text: str) -> int | None:
-    match_result = violation_line_pattern().match(violation_text)
-    if match_result is None:
-        return None
-    return int(match_result.group(1))
-
-
-def split_violations_by_scope(
-    issues: list[str],
-    added_line_numbers: set[int] | None,
-) -> tuple[list[str], list[str]]:
-    if added_line_numbers is None:
-        return list(issues), []
-    blocking: list[str] = []
-    advisory: list[str] = []
-    for each_issue in issues:
-        violation_line = extract_violation_line_number(each_issue)
-        if violation_line is None:
-            blocking.append(each_issue)
-            continue
-        if violation_line in added_line_numbers:
-            blocking.append(each_issue)
-        else:
-            advisory.append(each_issue)
-    return blocking, advisory
-
-
-def print_violation_section(
-    header_message: str,
-    violations_by_file: dict[Path, list[str]],
-    repository_root: Path,
-) -> None:
-    print(header_message, file=sys.stderr)
-    resolved_root = repository_root.resolve()
-    for each_path in sorted(violations_by_file.keys()):
-        relative = each_path.relative_to(resolved_root)
-        print(f"{relative}:", file=sys.stderr)
-        for each_issue in violations_by_file[each_path]:
-            print(f"  {each_issue}", file=sys.stderr)
-
-
-def run_gate(
-    validate_content,
-    file_paths: list[Path],
-    repository_root: Path,
-    added_lines_map: dict[Path, set[int]] | None = None,
-) -> int:
-    blocking_by_file: dict[Path, list[str]] = {}
-    advisory_by_file: dict[Path, list[str]] = {}
-    for file_path in sorted(set(file_paths)):
-        try:
-            resolved = file_path.resolve()
-        except OSError:
-            continue
-        try:
-            resolved.relative_to(repository_root.resolve())
-        except ValueError:
-            continue
-        if not is_code_path(resolved):
-            continue
-        if not resolved.is_file():
-            continue
-        try:
-            content = resolved.read_text(encoding="utf-8")
-        except OSError:
-            print(f"bugteam_code_rules_gate: skip unreadable {resolved}", file=sys.stderr)
-            continue
-        relative = resolved.relative_to(repository_root.resolve())
-        issues = validate_content(content, str(relative).replace("\\", "/"), old_content=content)
-        issues.extend(check_database_column_string_magic(content, str(relative).replace("\\", "/")))
-        issues.extend(check_wrapper_plumb_through(content, str(relative).replace("\\", "/")))
-        if not issues:
-            continue
-        added_for_file = None if added_lines_map is None else added_lines_map.get(resolved)
-        blocking, advisory = split_violations_by_scope(issues, added_for_file)
-        if blocking:
-            blocking_by_file[resolved] = blocking
-        if advisory:
-            advisory_by_file[resolved] = advisory
-    blocking_count = sum(len(each_list) for each_list in blocking_by_file.values())
-    advisory_count = sum(len(each_list) for each_list in advisory_by_file.values())
-    if blocking_count:
-        if added_lines_map is None:
-            header = f"bugteam_code_rules_gate: {blocking_count} violation(s) reported."
-        else:
-            header = (
-                f"bugteam_code_rules_gate: {blocking_count} violation(s) "
-                "introduced on changed lines:"
-            )
-        print_violation_section(
-            header,
-            blocking_by_file,
-            repository_root,
-        )
-    if advisory_count:
-        if blocking_count:
-            print("", file=sys.stderr)
-        print_violation_section(
-            (
-                f"bugteam_code_rules_gate: {advisory_count} pre-existing violation(s) "
-                "in touched files (advisory, not blocking):"
-            ),
-            advisory_by_file,
-            repository_root,
-        )
-    if blocking_count:
-        return 1
-    return 0
-
-
-def parse_arguments(argv: list[str]) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description=(
-            "Run CODE_RULES validators (validate_content) on files in the working tree. "
-            "Default file set: git diff --name-only merge-base(base)..HEAD."
-        ),
-    )
-    parser.add_argument(
-        "--repo-root",
-        type=Path,
-        default=None,
-        help="Repository root (default: cwd).",
-    )
-    parser.add_argument(
-        "--base",
-        default="origin/main",
-        help="Merge-base ref for git diff (default: origin/main).",
-    )
-    parser.add_argument(
-        "--staged",
-        action="store_true",
-        default=False,
-        help=(
-            "Scope to staged changes only (git diff --cached). "
-            "Blocks on violations introduced on staged-added lines; "
-            "reports pre-existing violations in touched files as advisory."
-        ),
-    )
-    parser.add_argument(
-        "--only-under",
-        action="append",
-        default=[],
-        dest="only_under",
-        metavar="PREFIX",
-        help=(
-            "After resolving the merge-base diff, keep only files whose repo-relative path "
-            "uses POSIX slashes and starts with PREFIX or equals PREFIX (repeatable)."
-        ),
-    )
-    parser.add_argument(
-        "paths",
-        nargs="*",
-        type=Path,
-        help="Optional explicit files; if set, git diff is not used.",
-    )
-    return parser.parse_args(argv)
-
-
-def main(argv: list[str] | None = None) -> int:
-    arguments = parse_arguments(sys.argv[1:] if argv is None else argv)
-    repository_root = (
-        arguments.repo_root.resolve()
-        if arguments.repo_root is not None
-        else Path.cwd().resolve()
-    )
-    validate_content = load_validate_content()
-    if arguments.paths:
-        file_paths = [repository_root / path for path in arguments.paths]
-        return run_gate(validate_content, file_paths, repository_root, added_lines_map=None)
-    if arguments.staged:
-        staged_file_paths = paths_from_git_staged(repository_root)
-        staged_file_paths = filter_paths_under_prefixes(
-            staged_file_paths,
-            repository_root,
-            arguments.only_under,
-        )
-        if not staged_file_paths:
-            return 0
-        staged_added_lines = added_lines_by_file_staged(repository_root, staged_file_paths)
-        return run_gate(
-            validate_content,
-            staged_file_paths,
-            repository_root,
-            added_lines_map=staged_added_lines,
-        )
-    file_paths = paths_from_git_diff(repository_root, arguments.base)
-    file_paths = filter_paths_under_prefixes(
-        file_paths,
-        repository_root,
-        arguments.only_under,
-    )
-    if not file_paths:
-        return 0
-    scoped_added_lines = added_lines_by_file(repository_root, arguments.base, file_paths)
-    return run_gate(
-        validate_content,
-        file_paths,
-        repository_root,
-        added_lines_map=scoped_added_lines,
-    )
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())