claude-dev-env 1.0.0

package/hooks/validation/code-style-validator.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""
+Code style validator - checks for common style issues.
+
+- 4-space indentation (not tabs, not 2 spaces)
+- Single newlines between functions (not double)
+- Single newlines between class methods
+"""
+import json
+import re
+import sys
+
+
+def check_indentation(content: str) -> list[str]:
+    """Check for non-4-space indentation."""
+    issues = []
+    lines = content.split('\n')
+
+    for line_num, line in enumerate(lines, 1):
+        if not line or not line[0].isspace():
+            continue
+
+        # Check for tabs
+        if '\t' in line:
+            issues.append(f"Line {line_num}: Tab indentation - use 4 spaces")
+            continue
+
+        # Get leading spaces
+        stripped = line.lstrip(' ')
+        indent = len(line) - len(stripped)
+
+        # Check if indent is multiple of 4
+        if indent > 0 and indent % 4 != 0:
+            issues.append(f"Line {line_num}: {indent}-space indent - use 4 spaces")
+
+    return issues[:5]  # Limit to first 5
+
+
+def check_function_spacing(content: str) -> list[str]:
+    """Check for excessive blank lines between code blocks.
+
+    Detects 2+ consecutive blank lines anywhere in the file, plus validates
+    correct spacing before function/method/class definitions.
+    """
+    issues = []
+    lines = content.split('\n')
+
+    func_pattern = re.compile(r'^(\s*)(async\s+)?def\s+\w+')
+    class_pattern = re.compile(r'^class\s+\w+')
+
+    consecutive_blank_count = 0
+    blank_run_start_line = 0
+    prev_was_code = False
+
+    for line_num, line in enumerate(lines, 1):
+        stripped = line.strip()
+
+        if not stripped:
+            if consecutive_blank_count == 0:
+                blank_run_start_line = line_num
+            consecutive_blank_count += 1
+            continue
+
+        if consecutive_blank_count >= 3:
+            issues.append(f"Line {blank_run_start_line}: {consecutive_blank_count} consecutive blank lines - max 2 allowed")
+
+        func_match = func_pattern.match(line)
+        class_match = class_pattern.match(line)
+
+        if func_match and prev_was_code:
+            indent = len(func_match.group(1)) if func_match.group(1) else 0
+
+            if indent == 0:
+                if consecutive_blank_count != 2:
+                    issues.append(f"Line {line_num}: Top-level function needs 2 blank lines above (has {consecutive_blank_count})")
+            else:
+                if consecutive_blank_count != 1:
+                    issues.append(f"Line {line_num}: Method needs 1 blank line above (has {consecutive_blank_count})")
+
+        elif class_match and prev_was_code:
+            if consecutive_blank_count != 2:
+                issues.append(f"Line {line_num}: Class needs 2 blank lines above (has {consecutive_blank_count})")
+
+        consecutive_blank_count = 0
+        prev_was_code = not stripped.startswith('#') and not stripped.startswith('@')
+
+    return issues[:5]
+
+
+def main() -> None:
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if not file_path:
+        sys.exit(0)
+
+    # Only check Python files
+    if not file_path.endswith('.py'):
+        sys.exit(0)
+
+    # Skip test files (more lenient)
+    if 'test' in file_path.lower() or 'conftest' in file_path.lower():
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    content = tool_input.get("content", "") or tool_input.get("new_string", "")
+
+    if not content:
+        sys.exit(0)
+
+    if tool_name == "Write":
+        try:
+            with open(file_path, "r", encoding="utf-8") as existing_file:
+                existing_content = existing_file.read()
+            if existing_content:
+                sys.exit(0)
+        except (FileNotFoundError, OSError, UnicodeDecodeError):
+            pass
+
+    issues = []
+    issues.extend(check_indentation(content))
+    issues.extend(check_function_spacing(content))
+
+    if issues:
+        issue_list = "; ".join(issues)
+        result = {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "ask",
+                "permissionDecisionReason": f"[Code Style] {len(issues)} issue(s): {issue_list}. Fix or proceed?"
+            }
+        }
+        print(json.dumps(result))
+        sys.stdout.flush()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/validation/e2e-test-validator.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""
+Validate E2E test consistency between online/offline specs.
+
+Two checks:
+1. Naming: offline tests must mirror online test names with " offline" suffix.
+2. Coverage: when a new online e2e test file is written, a corresponding
+   offline equivalent must exist. Blocks if missing.
+
+Triggered as PostToolUse hook when editing spec files.
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+
+E2E_TEST_DIRECTORY = "frontend/tests/e2e"
+
+
+def extract_test_names(file_path: Path) -> set[str]:
+    """Extract test names from spec file."""
+    content = file_path.read_text()
+    pattern = r"test\(['\"]([^'\"]+)['\"]"
+    return set(re.findall(pattern, content))
+
+
+def validate_e2e_naming(project_root: Path) -> list[str]:
+    """Return list of naming violations.
+
+    Only validates tests that follow the naming convention (end with " offline").
+    Legacy tests without the suffix are ignored - they may intentionally differ.
+    """
+    online = project_root / E2E_TEST_DIRECTORY / "online.spec.ts"
+    offline = project_root / E2E_TEST_DIRECTORY / "offline.spec.ts"
+
+    if not online.exists() or not offline.exists():
+        return []
+
+    online_tests = extract_test_names(online)
+    offline_tests = extract_test_names(offline)
+
+    violations = []
+
+    for test in offline_tests:
+        if not test.endswith(" offline"):
+            continue
+
+        online_name = test.removesuffix(" offline")
+        if online_name not in online_tests:
+            violations.append(f"No online pair for: '{test}'")
+
+    return violations
+
+
+def validate_offline_coverage(file_path: str, project_root: Path) -> list[str]:
+    """Check that online e2e test files have a corresponding offline file.
+
+    When a new online spec file is written, the offline equivalent must exist.
+    Returns blocking violations if offline file is missing.
+    """
+    e2e_directory = project_root / E2E_TEST_DIRECTORY
+    file_name = Path(file_path).name
+
+    if "offline" in file_name:
+        return []
+
+    if not file_name.endswith(".spec.ts"):
+        return []
+
+    offline_name = file_name.replace(".spec.ts", ".offline.spec.ts")
+    if file_name == "online.spec.ts":
+        offline_name = "offline.spec.ts"
+
+    offline_path = e2e_directory / offline_name
+    if not offline_path.exists():
+        return [f"Missing offline equivalent: {offline_name} required for {file_name}"]
+
+    return []
+
+
+def main() -> None:
+    """Hook entry point - reads tool input from stdin."""
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if not file_path:
+        sys.exit(0)
+
+    if ".spec.ts" not in file_path:
+        sys.exit(0)
+
+    path_object = Path(file_path)
+    project_root = path_object.parent
+    while project_root != project_root.parent:
+        if (project_root / E2E_TEST_DIRECTORY).exists():
+            break
+        project_root = project_root.parent
+    else:
+        sys.exit(0)
+
+    if not (project_root / E2E_TEST_DIRECTORY).exists():
+        sys.exit(0)
+
+    naming_violations = validate_e2e_naming(project_root)
+    coverage_violations = validate_offline_coverage(file_path, project_root)
+
+    if coverage_violations:
+        violation_list = "; ".join(coverage_violations)
+        result = {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": f"[E2E COVERAGE] Offline test required: {violation_list}"
+            }
+        }
+        print(json.dumps(result))
+        sys.stdout.flush()
+        sys.exit(0)
+
+    if naming_violations:
+        violation_list = "; ".join(naming_violations)
+        result = {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": f"[E2E NAMING] {violation_list}. Offline tests must mirror online names with ' offline' suffix."
+            }
+        }
+        print(json.dumps(result))
+        sys.stdout.flush()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/validation/hook-format-validator.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""
+PostToolUse hook that validates hook commands in settings.json use cross-platform format.
+Blocks if hooks use simple 'python3 ~/.claude/...' instead of the exec(open(...)) pattern.
+"""
+
+import json
+import re
+import sys
+
+
+SIMPLE_PATTERN = re.compile(
+    r'python3?\s+~/\.claude/hooks/'
+)
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_input = hook_input.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if not file_path.endswith("settings.json"):
+        sys.exit(0)
+
+    if "/.claude/" not in file_path and "\\.claude\\" not in file_path:
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    content = tool_input.get("content", "")
+    if not content:
+        new_string = tool_input.get("new_string", "")
+        content = new_string
+
+    if tool_name == "Write" and content:
+        try:
+            with open(file_path, "r", encoding="utf-8") as existing_file:
+                existing_content = existing_file.read()
+            if existing_content:
+                sys.exit(0)
+        except (FileNotFoundError, OSError, UnicodeDecodeError):
+            pass
+
+    if not content:
+        sys.exit(0)
+
+    if SIMPLE_PATTERN.search(content):
+        message = "BLOCKED: Hook uses python3 ~/.claude/hooks/... format which breaks cross-platform. Use this pattern: node -e \"process.argv.splice(1,0,'_');require(require('os').homedir()+'/.claude/hooks/run-hook-wrapper.js')\" \"subfolder/your-hook.py\""
+        result = {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": message
+            }
+        }
+        print(json.dumps(result))
+        sys.exit(0)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/validation/mypy_validator.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""
+Mypy validation hook - blocks Write/Edit if mypy finds type errors.
+
+This catches:
+- Missing attributes (e.g., HumanActions has no attribute 'press_key')
+- Wrong function signatures
+- Type mismatches
+- Import errors
+
+Works in both WSL and Windows for any Python project with a git root.
+Project root is discovered via CLAUDE_PROJECT_ROOT env var or git rev-parse.
+"""
+import json
+import os
+import platform
+import subprocess
+import sys
+from pathlib import Path
+
+IS_WINDOWS = platform.system() == "Windows"
+
+GIT_COMMAND_TIMEOUT_SECONDS = 5
+MYPY_TIMEOUT_SECONDS = 60
+MAXIMUM_DISPLAYED_ERRORS = 5
+
+SKIP_PATTERNS = {"test_", "_test.", "conftest", "/tests/", "\\tests\\", "fixture", "mock"}
+
+
+def discover_project_root(target_file: str) -> Path | None:
+    if env_root := os.environ.get("CLAUDE_PROJECT_ROOT"):
+        return Path(env_root)
+
+    try:
+        completed_process = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            timeout=GIT_COMMAND_TIMEOUT_SECONDS,
+            cwd=str(Path(target_file).parent),
+        )
+        if completed_process.returncode != 0:
+            return None
+        return Path(completed_process.stdout.strip())
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return None
+
+
+def is_file_within_project(target_file: str, project_root: Path) -> bool:
+    try:
+        Path(target_file).resolve().relative_to(project_root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def build_mypy_command(relative_file_path: str) -> list[str]:
+    if IS_WINDOWS:
+        base_command = [sys.executable, "-m", "mypy"]
+    else:
+        base_command = ["mypy"]
+
+    return base_command + [
+        "--no-error-summary",
+        "--show-error-codes",
+        "--no-color",
+        relative_file_path,
+    ]
+
+
+def run_mypy(target_file: str, project_root: str) -> tuple[int, str]:
+    relative_file_path = os.path.relpath(target_file, project_root)
+    mypy_command = build_mypy_command(relative_file_path)
+
+    completed_process = subprocess.run(
+        mypy_command,
+        capture_output=True,
+        text=True,
+        env=os.environ.copy(),
+        timeout=MYPY_TIMEOUT_SECONDS,
+        cwd=project_root,
+    )
+
+    stdout_output = completed_process.stdout.strip()
+    stderr_output = completed_process.stderr.strip()
+    combined_output = f"{stdout_output}\n{stderr_output}".strip() if stderr_output else stdout_output
+
+    return completed_process.returncode, combined_output
+
+
+def extract_error_lines(mypy_output: str) -> list[str]:
+    all_lines = mypy_output.strip().split("\n")
+    return [each_line for each_line in all_lines if ": error:" in each_line]
+
+
+def format_error_summary(all_error_lines: list[str]) -> str:
+    displayed_errors = all_error_lines[:MAXIMUM_DISPLAYED_ERRORS]
+    error_summary = "\n".join(f"  {each_line}" for each_line in displayed_errors)
+
+    remaining_error_count = len(all_error_lines) - MAXIMUM_DISPLAYED_ERRORS
+    if remaining_error_count > 0:
+        error_summary += f"\n  ... and {remaining_error_count} more"
+
+    return error_summary
+
+
+def build_block_response(error_summary: str) -> dict[str, str | dict[str, str]]:
+    return {
+        "decision": "block",
+        "reason": f"[MYPY] Type errors: {error_summary}",
+        "hookSpecificOutput": {
+            "hookEventName": "PostToolUse",
+        },
+    }
+
+
+def parse_file_path_from_stdin() -> str:
+    try:
+        hook_event = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return ""
+
+    return hook_event.get("tool_input", {}).get("file_path", "")
+
+
+def is_test_file(python_file: Path) -> bool:
+    name_lower = python_file.name.lower()
+    path_lower = str(python_file).lower()
+
+    return any(
+        each_pattern in name_lower or each_pattern in path_lower
+        for each_pattern in SKIP_PATTERNS
+    )
+
+
+def main() -> None:
+    target_file_path = parse_file_path_from_stdin()
+
+    if not target_file_path:
+        sys.exit(0)
+
+    target_file = Path(target_file_path)
+
+    if target_file.suffix.lower() != ".py":
+        sys.exit(0)
+
+    if is_test_file(target_file):
+        sys.exit(0)
+
+    if not target_file.exists():
+        sys.exit(0)
+
+    project_root = discover_project_root(target_file_path)
+    if project_root is None:
+        sys.exit(0)
+
+    if not is_file_within_project(target_file_path, project_root):
+        sys.exit(0)
+
+    try:
+        mypy_exit_code, mypy_output = run_mypy(target_file_path, str(project_root))
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        sys.exit(0)
+
+    if mypy_exit_code == 0:
+        sys.exit(0)
+
+    all_error_lines = extract_error_lines(mypy_output)
+
+    if not all_error_lines:
+        sys.exit(0)
+
+    error_summary = format_error_summary(all_error_lines)
+    block_response = build_block_response(error_summary)
+    print(json.dumps(block_response))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/validators/README.md

@@ -0,0 +1,125 @@
+# Python Style Validators
+
+AST-based Python style checks for code quality enforcement.
+
+## Checks Implemented
+
+1. **Imports at top** - All import statements must be at the top of the file
+2. **No empty line after decorators** - Decorators must be directly above functions (no blank lines)
+3. **Single empty line between functions** - Exactly one blank line between top-level functions
+4. **View function naming** - Functions in `views.py` with `request` parameter must end with `_view`
+
+## Usage
+
+### Command Line
+
+```bash
+python python_style_checks.py file1.py file2.py ...
+```
+
+Exit codes:
+- `0` - All files pass
+- `1` - Violations found or error
+
+### Python API
+
+```python
+from python_style_checks import validate_file, Violation
+from pathlib import Path
+
+violations = validate_file(Path("myfile.py"))
+for v in violations:
+    print(v)  # Prints: file:line: message
+```
+
+### Individual Checks
+
+```python
+import ast
+from python_style_checks import (
+    check_imports_at_top,
+    check_no_empty_line_after_decorators,
+    check_single_empty_line_between_functions,
+    check_view_function_naming,
+)
+
+source = Path("myfile.py").read_text()
+tree = ast.parse(source)
+
+# Run individual checks
+violations = check_imports_at_top(tree, "myfile.py")
+violations = check_no_empty_line_after_decorators(source, "myfile.py")
+violations = check_single_empty_line_between_functions(source, "myfile.py")
+violations = check_view_function_naming(tree, "views.py")
+```
+
+## Testing
+
+```bash
+pytest test_python_style_checks.py -v
+```
+
+## Examples
+
+### Valid Code
+
+```python
+"""Module docstring."""
+
+import os
+import sys
+from typing import List
+
+
+def foo() -> None:
+    """Do something."""
+    pass
+
+@decorator
+def bar() -> None:
+    """Another function."""
+    pass
+```
+
+### Invalid Code
+
+```python
+# Import not at top
+def foo() -> None:
+    pass
+
+import os  # VIOLATION: Import must be at top
+
+# Empty line after decorator
+@decorator
+
+def bar() -> None:  # VIOLATION: No empty line after decorator
+    pass
+
+# Wrong spacing between functions
+def baz() -> None:
+    pass
+
+
+def qux() -> None:  # VIOLATION: Expected 1 empty line, found 2
+    pass
+
+# View naming (in views.py)
+def user_profile(request):  # VIOLATION: Must end with _view
+    pass
+```
+
+## Integration with Pre-Commit Hooks
+
+Example `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: python-style-checks
+        name: Python Style Checks
+        entry: python hooks/validators/python_style_checks.py
+        language: system
+        types: [python]
+```