claude-dev-env 1.0.0

package/hooks/validators/VALIDATION_REPORT.md

@@ -0,0 +1,287 @@
+# Test Safety Checks Validator - Comprehensive Validation Report
+
+## Executive Summary
+
+**Critical Gaps Found: 2**
+**Minor Issues: 1**
+**Tests Passed: 14/17**
+
+---
+
+## Check 1: No Skip Decorators
+
+### Test Results
+
+| Test Case | Expected | Result | Status |
+|-----------|----------|--------|--------|
+| `@skip` | CAUGHT | CAUGHT | PASS |
+| `@pytest.mark.skipif(...)` | CAUGHT | CAUGHT | PASS |
+| `@unittest.skipIf(...)` | CAUGHT | CAUGHT | PASS |
+| `@skip()` with parentheses | CAUGHT | CAUGHT | PASS |
+| `@pytest.mark.xfail` | ALLOWED | ALLOWED | PASS |
+| `@skip_on_windows` custom | ALLOWED | ALLOWED | PASS |
+| `@Skip` (capital S) | CAUGHT | **ALLOWED** | **FAIL** |
+| `@unittest.skipUnless(...)` | CAUGHT | CAUGHT | PASS |
+| `@pytest.mark.skip` (no args) | CAUGHT | CAUGHT | PASS |
+
+### GAP #1: Case-Sensitive Decorator Matching
+
+**Severity: MEDIUM**
+
+**Issue:** The validator uses case-sensitive matching, so `@Skip` (capital S) is NOT caught.
+
+**Current Code (lines 16-22):**
+```python
+SKIP_DECORATOR_NAMES = frozenset([
+    "skip",
+    "skipif",
+    "skipunless",
+    "skipIf",
+    "skipUnless",
+])
+```
+
+**Problem:** This misses decorators with different capitalization like `@Skip`, `@SkipIf`, `@SKIP`, etc.
+
+**Recommended Fix:**
+```python
+def _get_decorator_name(decorator: ast.expr) -> str:
+    """Extract the name from a decorator node (lowercase for comparison)."""
+    # ... existing logic ...
+    return name.lower()  # Convert to lowercase for case-insensitive matching
+```
+
+Then update the frozenset to all lowercase:
+```python
+SKIP_DECORATOR_NAMES = frozenset([
+    "skip",
+    "skipif",
+    "skipunless",
+])
+```
+
+**Impact:** Currently allows `@Skip`, `@SkipIf`, `@SkipUnless` to slip through.
+
+---
+
+## Check 2: DEBUG Guard in Management Commands
+
+### Test Results
+
+| Test Case | Expected | Result | Status |
+|-----------|----------|--------|--------|
+| No DEBUG check | CAUGHT | CAUGHT | PASS |
+| `if not settings.DEBUG: raise` | ALLOWED | ALLOWED | PASS |
+| `if not settings.DEBUG: return` | ALLOWED | ALLOWED | PASS |
+| Using imported `DEBUG` variable | CAUGHT | CAUGHT | PASS |
+| DEBUG check in helper function | CAUGHT | CAUGHT | PASS |
+| DEBUG check after 5 statements | CAUGHT | CAUGHT | PASS |
+| `if settings.DEBUG: ... else: raise` | ALLOWED | **CAUGHT** | **FAIL** |
+| `if not settings.DEBUG and X:` | DEBATABLE | CAUGHT | WARN |
+| File not in `management/commands/` | IGNORED | IGNORED | PASS |
+
+### GAP #2: Positive DEBUG Check Pattern Rejected
+
+**Severity: HIGH**
+
+**Issue:** The validator incorrectly rejects the pattern `if settings.DEBUG: ... else: raise`.
+
+**Test File:** `cmd_07_positive_debug_check.py`
+```python
+def handle(self, *args, **options):
+    if settings.DEBUG:
+        print("Running in DEBUG mode")
+    else:
+        raise CommandError("This command can only be run in DEBUG mode")
+```
+
+**Expected:** ALLOWED (this is a valid DEBUG guard)
+**Actual:** CAUGHT (flagged as violation)
+
+**Root Cause (lines 186-187):**
+```python
+if _is_debug_check(test) and stmt.orelse:
+    return False  # This returns False when it should return True!
+```
+
+**The Logic Flaw:**
+- Line 186: Detects `if settings.DEBUG:` and checks if there's an `else` clause
+- Line 187: Returns `False` (no DEBUG guard found)
+- **BUG:** This should return `True` because the pattern IS a valid guard!
+
+**Recommended Fix:**
+```python
+def _has_debug_guard(func: ast.FunctionDef) -> bool:
+    """Check if a function has a settings.DEBUG guard at the start."""
+    if not func.body:
+        return False
+
+    for stmt in func.body[:5]:
+        if isinstance(stmt, ast.If):
+            test = stmt.test
+
+            # Pattern 1: if not settings.DEBUG: raise/return
+            if isinstance(test, ast.UnaryOp) and isinstance(test.op, ast.Not):
+                if _is_debug_check(test.operand):
+                    return True
+
+            # Pattern 2: if settings.DEBUG: ... else: raise/return
+            if _is_debug_check(test):
+                if stmt.orelse:
+                    # Check if else clause has raise/return
+                    if _has_early_exit(stmt.orelse):
+                        return True
+                # if settings.DEBUG: with no else is also valid
+                return True
+
+    return False
+
+
+def _has_early_exit(statements: List[ast.stmt]) -> bool:
+    """Check if statements contain raise or return."""
+    for stmt in statements:
+        if isinstance(stmt, (ast.Raise, ast.Return)):
+            return True
+        # Check nested if/else
+        if isinstance(stmt, ast.If):
+            if _has_early_exit(stmt.body) or (stmt.orelse and _has_early_exit(stmt.orelse)):
+                return True
+    return False
+```
+
+**Impact:** Currently REJECTS valid DEBUG guard patterns, forcing developers to use only negative checks.
+
+### MINOR ISSUE: Complex Boolean Expressions
+
+**Severity: LOW**
+
+**Issue:** The validator rejects `if not settings.DEBUG and other_condition:`.
+
+**Test File:** `cmd_08_debug_with_and.py`
+```python
+if not settings.DEBUG and True:
+    raise CommandError("This command can only be run in DEBUG mode")
+```
+
+**Expected:** DEBATABLE (could be allowed if DEBUG is the primary condition)
+**Actual:** CAUGHT (flagged as violation)
+
+**Analysis:**
+- Current code only checks for simple `UnaryOp(Not)` with `settings.DEBUG`
+- Doesn't handle `BoolOp` (and/or) expressions
+- This is arguably correct behavior - keeps the check simple and strict
+
+**Recommendation:** Document this limitation. Developers should use:
+```python
+if not settings.DEBUG:
+    raise CommandError("...")
+# Then check other conditions separately
+```
+
+---
+
+## Additional Edge Cases Tested
+
+### Nested Directory Structure
+- File in `management/commands/subdir/command.py` - NOT tested
+- **Recommendation:** Add test case to verify path matching works with subdirectories
+
+### File Encoding Issues
+- Files with syntax errors - Handled gracefully (returns empty violations)
+- Files that don't exist - Handled with error message
+
+### Multiple Commands in One File
+- NOT tested
+- **Recommendation:** Add test case with multiple Command classes in one file
+
+---
+
+## Recommended Priority Fixes
+
+1. **HIGH PRIORITY:** Fix GAP #2 (positive DEBUG check pattern)
+   - Current behavior rejects valid code
+   - Breaking change for developers using this pattern
+
+2. **MEDIUM PRIORITY:** Fix GAP #1 (case-sensitive skip decorators)
+   - Low probability but easy to fix
+   - Prevents trivial evasion
+
+3. **LOW PRIORITY:** Add test for nested management commands
+   - Verify path matching works with subdirectories
+
+---
+
+## Test Coverage Summary
+
+**Skip Decorators:**
+- Simple decorators: TESTED
+- Attribute decorators: TESTED
+- Called decorators: TESTED
+- Case variations: **GAP FOUND**
+- Custom decorators: TESTED (correctly allowed)
+
+**DEBUG Guards:**
+- No check: TESTED
+- Negative check (`if not`): TESTED
+- Positive check (`if ... else`): **GAP FOUND**
+- Imported DEBUG: TESTED (correctly rejected)
+- Helper function: TESTED (correctly rejected)
+- Late check (>5 statements): TESTED (correctly rejected)
+- Path matching: TESTED
+- Complex boolean: TESTED (debatable behavior)
+
+---
+
+## Files Created for Testing
+
+### Skip Decorators (9 files)
+```
+test_files/skip_decorators/
+├── test_01_simple_skip.py
+├── test_02_pytest_skipif.py
+├── test_03_unittest_skipIf.py
+├── test_04_skip_with_parens.py
+├── test_05_xfail.py
+├── test_06_custom_skip.py
+├── test_07_capital_Skip.py (GAP)
+├── test_08_skipUnless.py
+└── test_09_pytest_mark_skip_simple.py
+```
+
+### Management Commands (9 files)
+```
+test_files/management/commands/
+├── cmd_01_no_debug_check.py
+├── cmd_02_proper_debug_check.py
+├── cmd_03_debug_check_with_return.py
+├── cmd_04_imported_DEBUG.py
+├── cmd_05_debug_check_in_helper.py
+├── cmd_06_debug_check_late.py
+├── cmd_07_positive_debug_check.py (GAP)
+├── cmd_08_debug_with_and.py
+test_files/
+└── not_management_command.py
+```
+
+---
+
+## Conclusion
+
+The validator is **mostly effective** but has **2 critical gaps**:
+
+1. **Case-sensitive decorator matching** - Easy fix, low impact
+2. **Positive DEBUG check rejection** - HIGH PRIORITY, rejects valid code
+
+The implementation correctly handles:
+- Most skip decorator patterns
+- Simple DEBUG guard patterns
+- Path filtering for management commands
+- Graceful error handling
+
+**Overall Assessment: 82% effective (14/17 test cases passed)**
+
+**Action Required:**
+1. Fix GAP #2 immediately (breaking valid code)
+2. Fix GAP #1 for completeness
+3. Add test for nested management command directories
+4. Document the complex boolean limitation

package/hooks/validators/__init__.py

@@ -0,0 +1,19 @@
+"""Python style validation package."""
+
+from .python_style_checks import (
+    Violation,
+    check_imports_at_top,
+    check_no_empty_line_after_decorators,
+    check_single_empty_line_between_functions,
+    check_view_function_naming,
+    validate_file,
+)
+
+__all__ = [
+    "Violation",
+    "check_imports_at_top",
+    "check_no_empty_line_after_decorators",
+    "check_single_empty_line_between_functions",
+    "check_view_function_naming",
+    "validate_file",
+]

package/hooks/validators/abbreviation_checks.py

@@ -0,0 +1,82 @@
+"""Abbreviation detection validator.
+
+Implements check 5: No single-letter variable names (except i, j, k for loop counters).
+
+Detects:
+- Single-letter assignments: t = value
+- Single-letter loop variables: for f in files
+- Single-letter comprehension variables: [x for x in items]
+"""
+
+import ast
+import sys
+from pathlib import Path
+from typing import List, Set
+
+from validator_base import Violation
+
+
+ALLOWED_SINGLE_LETTERS: Set[str] = frozenset({"i", "j", "k", "_"})
+
+
+def check_single_letter_variables(tree: ast.AST, filename: str) -> List[Violation]:
+    violations: List[Violation] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+            if len(node.id) == 1 and node.id not in ALLOWED_SINGLE_LETTERS:
+                violations.append(
+                    Violation(
+                        filename,
+                        node.lineno,
+                        f"Single-letter variable '{node.id}' - use descriptive name",
+                    )
+                )
+
+    return violations
+
+
+def validate_file(file_path: Path) -> List[Violation]:
+    violations: List[Violation] = []
+    filename = str(file_path)
+
+    try:
+        source = file_path.read_text(encoding="utf-8")
+    except Exception as error:
+        violations.append(Violation(filename, 0, f"Error reading file: {error}"))
+        return violations
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as error:
+        violations.append(
+            Violation(filename, error.lineno or 0, f"Syntax error: {error.msg}")
+        )
+        return violations
+
+    violations.extend(check_single_letter_variables(tree, filename))
+    return violations
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("Usage: abbreviation_checks.py <file1.py> [file2.py ...]", file=sys.stderr)
+        return 1
+
+    all_violations: List[Violation] = []
+
+    for file_arg in sys.argv[1:]:
+        file_path = Path(file_arg)
+        if not file_path.exists():
+            print(f"Error: File not found: {file_path}", file=sys.stderr)
+            return 1
+        all_violations.extend(validate_file(file_path))
+
+    for violation in all_violations:
+        print(violation)
+
+    return 1 if all_violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/validators/code_quality_checks.py

@@ -0,0 +1,133 @@
+"""Code quality checks validator.
+
+Implements:
+- Check 30: Function too long (max 30 lines)
+- Check 31: Nesting too deep (max 2 levels)
+- Check 32: File too long (max 400 lines)
+"""
+
+import ast
+import sys
+from pathlib import Path
+from typing import List
+
+from validator_base import Violation
+
+
+MAX_FUNCTION_LINES = 30
+MAX_NESTING_DEPTH = 2
+MAX_FILE_LINES = 400
+
+
+def check_function_length(tree: ast.AST, filename: str) -> List[Violation]:
+    violations: List[Violation] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if node.end_lineno and node.lineno:
+                length = node.end_lineno - node.lineno + 1
+                if length > MAX_FUNCTION_LINES:
+                    violations.append(
+                        Violation(
+                            filename,
+                            node.lineno,
+                            f"Function '{node.name}' is {length} lines (max {MAX_FUNCTION_LINES})",
+                        )
+                    )
+
+    return violations
+
+
+def check_nesting_depth(tree: ast.AST, filename: str) -> List[Violation]:
+    violations: List[Violation] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            max_depth = _get_max_nesting_depth(node, 0)
+            if max_depth > MAX_NESTING_DEPTH:
+                violations.append(
+                    Violation(
+                        filename,
+                        node.lineno,
+                        f"Function '{node.name}' has nesting depth {max_depth} (max {MAX_NESTING_DEPTH})",
+                    )
+                )
+
+    return violations
+
+
+def _get_max_nesting_depth(node: ast.AST, current_depth: int) -> int:
+    max_depth = current_depth
+
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, (ast.If, ast.For, ast.While, ast.With, ast.Try)):
+            child_depth = _get_max_nesting_depth(child, current_depth + 1)
+            max_depth = max(max_depth, child_depth)
+        else:
+            child_depth = _get_max_nesting_depth(child, current_depth)
+            max_depth = max(max_depth, child_depth)
+
+    return max_depth
+
+
+def check_file_length(file_path: Path) -> List[Violation]:
+    violations: List[Violation] = []
+    filename = str(file_path)
+
+    try:
+        lines = file_path.read_text(encoding="utf-8").splitlines()
+    except Exception as error:
+        return [Violation(filename, 0, f"Error reading file: {error}")]
+
+    if len(lines) > MAX_FILE_LINES:
+        violations.append(
+            Violation(
+                filename,
+                1,
+                f"File is {len(lines)} lines (max {MAX_FILE_LINES}) - consider splitting",
+            )
+        )
+
+    return violations
+
+
+def validate_file(file_path: Path) -> List[Violation]:
+    violations: List[Violation] = []
+    filename = str(file_path)
+
+    violations.extend(check_file_length(file_path))
+
+    try:
+        source = file_path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+    except Exception as error:
+        return violations + [Violation(filename, 0, f"Error: {error}")]
+
+    violations.extend(check_function_length(tree, filename))
+    violations.extend(check_nesting_depth(tree, filename))
+
+    return violations
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("Usage: code_quality_checks.py <file1.py> [file2.py ...]", file=sys.stderr)
+        return 1
+
+    all_violations: List[Violation] = []
+
+    for file_arg in sys.argv[1:]:
+        file_path = Path(file_arg)
+        if not file_path.exists():
+            print(f"Error: File not found: {file_path}", file=sys.stderr)
+            return 1
+        all_violations.extend(validate_file(file_path))
+
+    for violation in all_violations:
+        print(violation)
+
+    return 1 if all_violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/validators/comment_checks.py

@@ -0,0 +1,188 @@
+"""Comment detection validator.
+
+Implements check 26: No comments in code (self-documenting code principle).
+
+Detects:
+- Python comments (# ...)
+- TypeScript/JavaScript comments (// ... and /* ... */)
+
+Exceptions (NOT flagged):
+- Shebang lines (#!/...)
+- Type annotations (type:, noqa, eslint-disable)
+- Docstrings (triple-quoted strings for function contracts)
+
+Note: Docstrings documenting function Args/Returns/Raises are acceptable
+per CODE_RULES.md. This validator only flags # and // style comments.
+"""
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List
+
+
+SHEBANG_PATTERN = re.compile(r"^#!")
+PYTHON_COMMENT_PATTERN = re.compile(r"(?<!.)#(?!!).+$|(?<=\s)#.+$", re.MULTILINE)
+JS_SINGLE_COMMENT_PATTERN = re.compile(r"//.*$", re.MULTILINE)
+JS_BLOCK_COMMENT_PATTERN = re.compile(r"/\*[\s\S]*?\*/", re.MULTILINE)
+
+
+@dataclass
+class Violation:
+    """Represents a comment violation."""
+
+    file: str
+    line: int
+    message: str
+
+    def __str__(self) -> str:
+        """Format as file:line: message."""
+        return f"{self.file}:{self.line}: {self.message}"
+
+
+def check_python_comments(source: str, filename: str) -> List[Violation]:
+    """Check for comments in Python files.
+
+    Args:
+        source: Source code as string
+        filename: Name of file being checked
+
+    Returns:
+        List of violations found
+    """
+    violations: List[Violation] = []
+    lines = source.splitlines()
+
+    for line_num, line in enumerate(lines, start=1):
+        stripped = line.lstrip()
+
+        if not stripped:
+            continue
+
+        if stripped.startswith("#"):
+            if SHEBANG_PATTERN.match(stripped):
+                continue
+
+            comment_text = stripped[1:].strip()[:40]
+            violations.append(
+                Violation(
+                    filename,
+                    line_num,
+                    f"Comment found: '# {comment_text}...' - code should be self-documenting",
+                )
+            )
+
+        elif "#" in line:
+            code_part, _, comment_part = line.partition("#")
+            if code_part.count('"') % 2 == 0 and code_part.count("'") % 2 == 0:
+                comment_text = comment_part.strip()[:40]
+                violations.append(
+                    Violation(
+                        filename,
+                        line_num,
+                        f"Inline comment found: '# {comment_text}...' - code should be self-documenting",
+                    )
+                )
+
+    return violations
+
+
+def check_js_comments(source: str, filename: str) -> List[Violation]:
+    """Check for comments in JavaScript/TypeScript files.
+
+    Args:
+        source: Source code as string
+        filename: Name of file being checked
+
+    Returns:
+        List of violations found
+    """
+    violations: List[Violation] = []
+    lines = source.splitlines()
+
+    for line_num, line in enumerate(lines, start=1):
+        stripped = line.lstrip()
+
+        if stripped.startswith("//"):
+            comment_text = stripped[2:].strip()[:40]
+            violations.append(
+                Violation(
+                    filename,
+                    line_num,
+                    f"Comment found: '// {comment_text}...' - code should be self-documenting",
+                )
+            )
+
+    for match in JS_BLOCK_COMMENT_PATTERN.finditer(source):
+        start_pos = match.start()
+        line_num = source[:start_pos].count("\n") + 1
+        comment_preview = match.group()[:40].replace("\n", " ")
+        violations.append(
+            Violation(
+                filename,
+                line_num,
+                f"Block comment found: '{comment_preview}...' - code should be self-documenting",
+            )
+        )
+
+    return violations
+
+
+def validate_file(file_path: Path) -> List[Violation]:
+    """Validate a file for comment violations.
+
+    Args:
+        file_path: Path to file to validate
+
+    Returns:
+        List of all violations found
+    """
+    violations: List[Violation] = []
+    filename = str(file_path)
+
+    try:
+        source = file_path.read_text(encoding="utf-8")
+    except Exception as error:
+        violations.append(Violation(filename, 0, f"Error reading file: {error}"))
+        return violations
+
+    suffix = file_path.suffix.lower()
+
+    if suffix == ".py":
+        violations.extend(check_python_comments(source, filename))
+    elif suffix in (".ts", ".tsx", ".js", ".jsx"):
+        violations.extend(check_js_comments(source, filename))
+
+    return violations
+
+
+def main() -> int:
+    """Main entry point for command-line usage.
+
+    Returns:
+        Exit code: 0 if all files pass, 1 if violations found
+    """
+    if len(sys.argv) < 2:
+        print("Usage: comment_checks.py <file1> [file2 ...]", file=sys.stderr)
+        return 1
+
+    all_violations: List[Violation] = []
+
+    for file_arg in sys.argv[1:]:
+        file_path = Path(file_arg)
+        if not file_path.exists():
+            print(f"Error: File not found: {file_path}", file=sys.stderr)
+            return 1
+
+        violations = validate_file(file_path)
+        all_violations.extend(violations)
+
+    for violation in all_violations:
+        print(violation)
+
+    return 1 if all_violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())