refactor: remove outdated test files and enhance hook functionality

- Deleted obsolete test files related to `Any` usage and `type: ignore` checks to streamline the codebase.
- Introduced new modules for message enrichment and type inference to improve error messaging and type suggestion capabilities in hooks.
- Updated `pyproject.toml` and `pyrightconfig.json` to include new dependencies and configurations for enhanced type checking.
- Improved the quality check mechanisms in the hooks to provide more detailed feedback and guidance on code quality issues.

HOOK_VALIDATION_REPORT.md

@@ -1,99 +0,0 @@
-# Hook Validation Report
-
-## ✅ COMPREHENSIVE TESTING COMPLETED
-
-All critical code quality hooks have been tested and are working correctly.
-
-## 🧪 Tests Performed
-
-### 1. Core Blocking Functionality
-- ✅ **Any usage blocking**: `typing.Any` usage properly denied
-- ✅ **Type ignore blocking**: `# type: ignore` usage properly denied
-- ✅ **Old typing patterns**: `Union`, `Optional`, `List`, `Dict` properly denied
-- ✅ **Good code allowed**: Modern typing syntax properly allowed
-- ✅ **Edit tool blocking**: Edit and MultiEdit tools also block bad patterns
-- ✅ **Non-Python files**: JSON, etc. properly allowed through
-
-### 2. Command Line Execution
-- ✅ **CLI blocking**: Hook properly blocks when executed via command line
-- ✅ **Exit codes**: Hook exits with code 2 (deny) when blocking
-- ✅ **JSON output**: Hook produces valid JSON responses
-- ✅ **Error propagation**: Blocking messages properly shown to user
-
-### 3. Global Configuration Testing
-- ✅ **Global hooks**: `~/.claude/settings.json` hooks working correctly
-- ✅ **Path resolution**: Hook path discovery working across projects
-- ✅ **biz-bud project**: Your original failing sample now properly blocked
-
-### 4. Enforcement Modes
-- ✅ **Strict mode**: Properly blocks (deny) forbidden patterns
-- ✅ **Configuration**: Enforcement mode set to "strict" by default
-- ✅ **Precheck issues**: Core violations (Any, type: ignore) always denied
-
-## 🛠️ Issues Found & Fixed
-
-1. **Fixed function signature**: `generate_test_quality_guidance` missing config parameter
-2. **Fixed path handling**: `sourcery_path` casting to string for subprocess
-3. **Fixed hook configuration**: Removed fallback `|| echo allow` that bypassed blocking
-
-## 📋 Evidence of Working Hooks
-
-### Your Original Sample (Now Blocked)
-```python
-def _add_to_service_collection(
-    self,
-    collection: dict[type[object], list[Any]],  # ← BLOCKED
-    service_type: type[object],
-    item: Any,  # ← BLOCKED
-    item_type: str,
-) -> None:
-    pass
-```
-
-**Result**: `permissionDecision: "deny"` with exit code 2
-
-### Test Results
-```
-🧪 Test 1: Any usage blocking
-✅ PASS: Any usage properly blocked
-
-🧪 Test 2: type: ignore blocking
-✅ PASS: type: ignore properly blocked
-
-🧪 Test 3: Old typing patterns blocking
-✅ PASS: Old typing patterns properly blocked
-
-🧪 Test 4: Good code allowed
-✅ PASS: Good code properly allowed
-
-🧪 Test 5: Edit tool blocking
-✅ PASS: Edit tool properly blocked
-
-🧪 Test 6: Non-Python files allowed
-✅ PASS: Non-Python files properly allowed
-
-📊 Results: 6 passed, 0 failed
-🎉 ALL CORE TESTS PASSED! Hooks are working correctly.
-```
-
-## 🚨 Critical Patterns Blocked
-
-The hooks now reliably block:
-
-1. **`typing.Any` usage** - Forces specific types
-2. **`# type: ignore` comments** - Forces proper typing fixes
-3. **Old typing patterns** - Enforces modern `str | int` syntax
-4. **Test quality issues** - Blocks conditionals/loops in tests (when Sourcery available)
-
-## 🎯 Hook Coverage
-
-- **PreToolUse**: Blocks bad code before writing
-- **PostToolUse**: Verifies code after writing
-- **All tools**: Write, Edit, MultiEdit all covered
-- **All projects**: Global configuration applies everywhere
-
-## ✅ Final Status
-
-**HOOKS ARE FULLY FUNCTIONAL AND BLOCKING CORRECTLY**
-
-The code quality guards are now bulletproof and will prevent the patterns you've been fighting. No more `Any` usage or `# type: ignore` will slip through.

hooks/code_quality_guard.py

@@ -13,18 +13,28 @@ import re
 import shutil
 import subprocess
 import sys
-from importlib import import_module
 import textwrap
 import tokenize
 from collections.abc import Callable
 from contextlib import suppress
 from dataclasses import dataclass
 from datetime import UTC, datetime
+from importlib import import_module
 from io import StringIO
 from pathlib import Path
 from tempfile import NamedTemporaryFile, gettempdir
 from typing import TYPE_CHECKING, TypedDict, cast
 
+# Import message enrichment helpers
+try:
+    from .message_enrichment import EnhancedMessageFormatter
+    from .type_inference import TypeInferenceHelper
+except ImportError:
+    # Fallback for direct execution
+    sys.path.insert(0, str(Path(__file__).parent))
+    from message_enrichment import EnhancedMessageFormatter
+    from type_inference import TypeInferenceHelper
+
 # Import internal duplicate detector; fall back to local path when executed directly
 if TYPE_CHECKING:
     from .internal_duplicate_detector import (
@@ -242,40 +252,33 @@ def _get_firecrawl_examples(rule_id: str, _api_key: str) -> str:
 def generate_test_quality_guidance(
     rule_id: str,
     content: str,
-    file_path: str,
+    _file_path: str,
     _config: "QualityConfig",
 ) -> str:
-    """Return concise guidance for test quality rule violations."""
+    """Return enriched guidance for test quality rule violations."""
     function_name = "test_function"
     match = re.search(r"def\s+(\w+)\s*\(", content)
     if match:
         function_name = match.group(1)
 
-    file_name = Path(file_path).name
+    # Extract a small snippet of the violating code
+    code_snippet = ""
+    if match:
+        # Try to get a few lines around the function definition
+        lines = content.splitlines()
+        for i, line in enumerate(lines):
+            if f"def {function_name}" in line:
+                snippet_start = max(0, i)
+                snippet_end = min(len(lines), i + 10)  # Show first 10 lines
+                code_snippet = "\n".join(lines[snippet_start:snippet_end])
+                break
 
-    guidance_map = {
-        "no-conditionals-in-tests": (
-            f"Test {function_name} contains conditional logic. "
-            "Parameterize or split tests so each scenario is explicit."
-        ),
-        "no-loop-in-tests": (
-            f"Test {function_name} iterates over data. Break the loop into "
-            "separate tests or use pytest parameterization."
-        ),
-        "raise-specific-error": (
-            f"Test {function_name} asserts generic exceptions. "
-            "Assert specific types to document the expected behaviour."
-        ),
-        "dont-import-test-modules": (
-            f"File {file_name} imports from tests. Move shared helpers into a "
-            "production module or provide them via fixtures."
-        ),
-    }
-
-    return guidance_map.get(
-        rule_id,
-        "Keep tests behaviour-focused: avoid conditionals, loops, generic exceptions, "
-        "and production dependencies on test helpers.",
+    # Use enhanced formatter for rich test quality messages
+    return EnhancedMessageFormatter.format_test_quality_message(
+        rule_id=rule_id,
+        function_name=function_name,
+        code_snippet=code_snippet,
+        include_examples=True,
     )
 
 
@@ -404,8 +407,7 @@ class QualityConfig:
             == "true",
             type_check_exit_code=int(os.getenv("QUALITY_TYPE_CHECK_EXIT_CODE", "2")),
             test_quality_enabled=(
-                os.getenv("QUALITY_TEST_QUALITY_ENABLED", "true").lower()
-                == "true"
+                os.getenv("QUALITY_TEST_QUALITY_ENABLED", "true").lower() == "true"
             ),
             context7_enabled=(
                 os.getenv("QUALITY_CONTEXT7_ENABLED", "false").lower() == "true"
@@ -446,9 +448,7 @@ def get_claude_quality_command(repo_root: Path | None = None) -> list[str]:
         ["python.exe", "python3.exe"] if is_windows else ["python", "python3"]
     )
     cli_names = (
-        ["claude-quality.exe", "claude-quality"]
-        if is_windows
-        else ["claude-quality"]
+        ["claude-quality.exe", "claude-quality"] if is_windows else ["claude-quality"]
     )
 
     candidates: list[tuple[Path, list[str]]] = []
@@ -521,7 +521,7 @@ def _format_basedpyright_errors(json_output: str) -> str:
             return "Type errors found (no details available)"
 
         # Group by severity and format
-        errors = []
+        errors: list[str] = []
         for diag in diagnostics[:10]:  # Limit to first 10 errors
             severity = diag.get("severity", "error").upper()
             message = diag.get("message", "Unknown error")
@@ -575,13 +575,14 @@ def _format_sourcery_errors(output: str) -> str:
         if "issue" in line.lower() and "detected" in line.lower():
             # Try to extract the number
             import re
+
             match = re.search(r"(\d+)\s+issue", line)
             if match:
                 issue_count = int(match.group(1))
             break
 
     # Format the output, removing redundant summary lines
-    formatted_lines = []
+    formatted_lines: list[str] = []
     for line in lines:
         # Skip the summary line as we'll add our own
         if "issue" in line.lower() and "detected" in line.lower():
@@ -877,9 +878,16 @@ def _find_project_root(file_path: str) -> Path:
 
     # Look for common project markers
     while current != current.parent:
-        if any((current / marker).exists() for marker in [
-            ".git", "pyrightconfig.json", "pyproject.toml", ".venv", "setup.py",
-        ]):
+        if any(
+            (current / marker).exists()
+            for marker in [
+                ".git",
+                "pyrightconfig.json",
+                "pyproject.toml",
+                ".venv",
+                "setup.py",
+            ]
+        ):
             return current
         current = current.parent
 
@@ -943,7 +951,10 @@ def analyze_code_quality(
         Path(tmp_path).unlink(missing_ok=True)
 
 
-def _check_internal_duplicates(results: AnalysisResults) -> list[str]:
+def _check_internal_duplicates(
+    results: AnalysisResults,
+    source_code: str = "",
+) -> list[str]:
     """Check for internal duplicate code within the same file."""
     issues: list[str] = []
     if "internal_duplicates" not in results:
@@ -954,13 +965,28 @@ def _check_internal_duplicates(results: AnalysisResults) -> list[str]:
         [],
     )
     for dup in duplicates[:3]:  # Show first 3
-        locations = ", ".join(
-            f"{loc['name']} ({loc['lines']})" for loc in dup.get("locations", [])
-        )
-        issues.append(
-            f"Internal duplication ({dup.get('similarity', 0):.0%} similar): "
-            f"{dup.get('description')} - {locations}",
+        # Use enhanced formatter for rich duplicate messages
+        duplicate_type = dup.get("type", "unknown")
+        similarity = dup.get("similarity", 0.0)
+        locations_raw = dup.get("locations", [])
+        # Cast to list of dicts for the formatter
+        locations_dicts: list[dict[str, str]] = [
+            {
+                "name": str(loc.get("name", "unknown")),
+                "type": str(loc.get("type", "code")),
+                "lines": str(loc.get("lines", "?")),
+            }
+            for loc in locations_raw
+        ]
+
+        enriched_message = EnhancedMessageFormatter.format_duplicate_message(
+            duplicate_type=str(duplicate_type),
+            similarity=float(similarity),
+            locations=locations_dicts,
+            source_code=source_code,
+            include_refactoring=True,
         )
+        issues.append(enriched_message)
     return issues
 
 
@@ -976,20 +1002,21 @@ def _check_complexity_issues(
     complexity_data = results["complexity"]
     summary = complexity_data.get("summary", {})
     avg_cc = summary.get("average_cyclomatic_complexity", 0.0)
-    if avg_cc > config.complexity_threshold:
-        issues.append(
-            f"High average complexity: CC={avg_cc:.1f} "
-            f"(threshold: {config.complexity_threshold})",
-        )
-
     distribution = complexity_data.get("distribution", {})
     high_count: int = (
         distribution.get("High", 0)
         + distribution.get("Very High", 0)
         + distribution.get("Extreme", 0)
     )
-    if high_count > 0:
-        issues.append(f"Found {high_count} function(s) with high complexity")
+
+    if avg_cc > config.complexity_threshold or high_count > 0:
+        # Use enhanced formatter for rich complexity messages
+        enriched_message = EnhancedMessageFormatter.format_complexity_message(
+            avg_complexity=avg_cc,
+            threshold=config.complexity_threshold,
+            high_count=high_count,
+        )
+        issues.append(enriched_message)
     return issues
 
 
@@ -1053,7 +1080,10 @@ def _check_modernization_issues(
     return issues
 
 
-def _check_type_checking_issues(results: AnalysisResults) -> list[str]:
+def _check_type_checking_issues(
+    results: AnalysisResults,
+    source_code: str = "",
+) -> list[str]:
     """Check for type checking issues from Sourcery, BasedPyright, and Pyrefly."""
     issues: list[str] = []
     if "type_checking" not in results:
@@ -1062,7 +1092,23 @@ def _check_type_checking_issues(results: AnalysisResults) -> list[str]:
     with suppress(AttributeError, TypeError):
         type_checking_data = results["type_checking"]
         type_issues = type_checking_data.get("issues", [])
-        issues.extend(str(issue_raw) for issue_raw in type_issues[:5])
+        # Group by tool and format with enhanced messages
+        for issue_str in type_issues[:3]:  # Limit to first 3 for brevity
+            issue_text = str(issue_str)
+            # Extract tool name (usually starts with "Tool:")
+            tool_name = "Type Checker"
+            if ":" in issue_text:
+                potential_tool = issue_text.split(":")[0].strip()
+                if potential_tool in ("Sourcery", "BasedPyright", "Pyrefly"):
+                    tool_name = potential_tool
+                    issue_text = ":".join(issue_text.split(":")[1:]).strip()
+
+            enriched_message = EnhancedMessageFormatter.format_type_error_message(
+                tool_name=tool_name,
+                error_output=issue_text,
+                source_code=source_code,
+            )
+            issues.append(enriched_message)
 
     return issues
 
@@ -1070,14 +1116,15 @@ def _check_type_checking_issues(results: AnalysisResults) -> list[str]:
 def check_code_issues(
     results: AnalysisResults,
     config: QualityConfig,
+    source_code: str = "",
 ) -> tuple[bool, list[str]]:
     """Check analysis results for issues that should block the operation."""
     issues: list[str] = []
 
-    issues.extend(_check_internal_duplicates(results))
+    issues.extend(_check_internal_duplicates(results, source_code))
     issues.extend(_check_complexity_issues(results, config))
     issues.extend(_check_modernization_issues(results, config))
-    issues.extend(_check_type_checking_issues(results))
+    issues.extend(_check_type_checking_issues(results, source_code))
 
     return len(issues) > 0, issues
 
@@ -1215,62 +1262,83 @@ def verify_naming_conventions(file_path: str) -> list[str]:
 
 
 def _detect_any_usage(content: str) -> list[str]:
-    """Detect forbidden typing.Any usage in proposed content."""
+    """Detect forbidden typing.Any usage and suggest specific types."""
+    # Use type inference helper to find Any usage with context
+    any_usages = TypeInferenceHelper.find_any_usage_with_context(content)
 
-    class _AnyUsageVisitor(ast.NodeVisitor):
-        """Collect line numbers where typing.Any is referenced."""
-
-        def __init__(self) -> None:
-            self.lines: set[int] = set()
-
-        def visit_Name(self, node: ast.Name) -> None:
-            if node.id == "Any":
-                self.lines.add(node.lineno)
-            self.generic_visit(node)
-
-        def visit_Attribute(self, node: ast.Attribute) -> None:
-            if node.attr == "Any":
-                self.lines.add(node.lineno)
-            self.generic_visit(node)
-
-        def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
-            for alias in node.names:
-                if alias.name == "Any" or alias.asname == "Any":
-                    self.lines.add(node.lineno)
-            self.generic_visit(node)
-
-        def visit_Import(self, node: ast.Import) -> None:
-            for alias in node.names:
-                if alias.name == "Any" or alias.asname == "Any":
-                    self.lines.add(node.lineno)
-            self.generic_visit(node)
-
-    lines_with_any: set[int] = set()
-    try:
-        # Dedent the content to handle code fragments with leading indentation
-        tree = ast.parse(textwrap.dedent(content))
-    except SyntaxError:
+    # Fallback to line-by-line check for syntax errors
+    if not any_usages:
+        lines_with_any: set[int] = set()
         for index, line in enumerate(content.splitlines(), start=1):
             code_portion = line.split("#", 1)[0]
             if re.search(r"\bAny\b", code_portion):
                 lines_with_any.add(index)
-    else:
-        visitor = _AnyUsageVisitor()
-        visitor.visit(tree)
-        lines_with_any = visitor.lines
 
-    if not lines_with_any:
+        if lines_with_any:
+            sorted_lines = sorted(lines_with_any)
+            display_lines = ", ".join(str(num) for num in sorted_lines[:5])
+            if len(sorted_lines) > 5:
+                display_lines += ", …"
+            return [
+                f"⚠️ Forbidden typing.Any usage at line(s) {display_lines}; "
+                "replace with specific types",
+            ]
+
+    if not any_usages:
         return []
 
-    sorted_lines = sorted(lines_with_any)
-    display_lines = ", ".join(str(num) for num in sorted_lines[:5])
-    if len(sorted_lines) > 5:
-        display_lines += ", …"
+    issues: list[str] = []
 
-    return [
-        "⚠️ Forbidden typing.Any usage at line(s) "
-        f"{display_lines}; replace with specific types",
-    ]
+    # Group by context type
+    by_context: dict[str, list[dict[str, str | int]]] = {}
+    for usage in any_usages:
+        context = str(usage.get("context", "unknown"))
+        if context not in by_context:
+            by_context[context] = []
+        by_context[context].append(usage)
+
+    # Format enriched messages for each context type
+    for context, usages_list in by_context.items():
+        lines = [str(u.get("line", "?")) for u in usages_list[:5]]
+        line_summary = ", ".join(lines)
+        if len(usages_list) > 5:
+            line_summary += ", ..."
+
+        # Get suggestions
+        suggestions: list[str] = []
+        for usage in usages_list[:3]:  # Show first 3 suggestions
+            element = str(usage.get("element", ""))
+            suggested = str(usage.get("suggested", ""))
+            if suggested and suggested not in {"Any", "Infer from usage"}:
+                suggestions.append(f"  • {element}: {suggested}")
+
+        parts: list[str] = [
+            f"⚠️ Forbidden typing.Any Usage ({context})",
+            f"📍 Lines: {line_summary}",
+        ]
+
+        if suggestions:
+            parts.append("💡 Suggested Types:")
+            parts.extend(suggestions)
+        else:
+            parts.append("💡 Tip: Replace `Any` with specific types based on usage")
+
+        parts.extend(
+            [
+                "",
+                "🔗 Common Replacements:",
+                "  • dict[str, Any] → dict[str, int] (or appropriate value type)",
+                "  • list[Any] → list[str] (or appropriate element type)",
+                (
+                    "  • Callable[..., Any] → Callable[[int, str], bool] "
+                    "(with specific signature)"
+                ),
+            ]
+        )
+
+        issues.append("\n".join(parts))
+
+    return issues
 
 
 def _detect_type_ignore_usage(content: str) -> list[str]:
@@ -1341,12 +1409,10 @@ def _detect_old_typing_patterns(content: str) -> list[str]:
                 lines_with_pattern.append(i)
 
         if lines_with_pattern:
-            display_lines = ", ".join(str(num) for num in lines_with_pattern[:5])
+            display_lines: str = ", ".join(str(num) for num in lines_with_pattern[:5])
             if len(lines_with_pattern) > 5:
                 display_lines += ", …"
-            issue_text = (
-                f"⚠️ Old typing pattern at line(s) {display_lines}: {message}"
-            )
+            issue_text: str = f"⚠️ Old typing pattern at line(s) {display_lines}: {message}"
             found_issues.append(issue_text)
 
     return found_issues
@@ -1387,7 +1453,7 @@ def _detect_suffix_duplication(file_path: str, content: str) -> list[str]:
             if existing_file != file_path_obj:
                 existing_stem = existing_file.stem
                 if existing_stem.startswith(f"{file_stem}_"):
-                    potential_suffix = existing_stem[len(file_stem)+1:]
+                    potential_suffix = existing_stem[len(file_stem) + 1 :]
                     if potential_suffix in SUSPICIOUS_SUFFIXES:
                         message = EXISTING_FILE_DUPLICATE_MSG.format(
                             current=file_path_obj.name,
@@ -1401,7 +1467,7 @@ def _detect_suffix_duplication(file_path: str, content: str) -> list[str]:
             if existing_file != file_path_obj:
                 existing_stem = existing_file.stem
                 if existing_stem.startswith(f"{file_stem}-"):
-                    potential_suffix = existing_stem[len(file_stem)+1:]
+                    potential_suffix = existing_stem[len(file_stem) + 1 :]
                     if potential_suffix in SUSPICIOUS_SUFFIXES:
                         message = EXISTING_FILE_DUPLICATE_MSG.format(
                             current=file_path_obj.name,
@@ -1505,7 +1571,7 @@ def _perform_quality_check(
         config,
         enable_type_checks=enable_type_checks,
     )
-    return check_code_issues(results, config)
+    return check_code_issues(results, config, content)
 
 
 def _handle_quality_issues(
@@ -1517,7 +1583,7 @@ def _handle_quality_issues(
 ) -> JsonObject:
     """Handle quality issues based on enforcement mode."""
     # Prepare denial message with formatted issues
-    formatted_issues = []
+    formatted_issues: list[str] = []
     for issue in issues:
         # Add indentation to multi-line issues for better readability
         if "\n" in issue:
@@ -1838,6 +1904,7 @@ def run_test_quality_checks(
         if not sourcery_path.exists():
             # Try to find sourcery in PATH
             import shutil
+
             sourcery_path = shutil.which("sourcery") or str(venv_bin / "sourcery")
 
         if not sourcery_path or not Path(sourcery_path).exists():

hooks/message_enrichment.py

@@ -0,0 +1,570 @@
+"""Enhanced message formatting with contextual awareness for hook outputs.
+
+Provides rich, actionable error messages with code examples and refactoring guidance.
+"""
+
+import ast
+import re
+import textwrap
+from dataclasses import dataclass
+from typing import cast
+
+
+@dataclass
+class CodeContext:
+    """Context information extracted from code for enriched messages."""
+
+    file_path: str
+    line_number: int
+    function_name: str | None
+    class_name: str | None
+    code_snippet: str
+    surrounding_context: str
+
+
+@dataclass
+class RefactoringStrategy:
+    """Suggested refactoring approach for code issues."""
+
+    strategy_type: str  # 'extract_function', 'use_inheritance', 'parameterize', etc.
+    description: str
+    example_before: str
+    example_after: str
+    benefits: list[str]
+
+
+class EnhancedMessageFormatter:
+    """Formats hook messages with context, examples, and actionable guidance."""
+
+    @staticmethod
+    def extract_code_context(
+        content: str,
+        line_number: int,
+        *,
+        context_lines: int = 3,
+    ) -> CodeContext:
+        """Extract code context around a specific line."""
+        lines = content.splitlines()
+        start = max(0, line_number - context_lines - 1)
+        end = min(len(lines), line_number + context_lines)
+
+        snippet_lines = lines[start:end]
+        snippet = "\n".join(
+            f"{i + start + 1:4d} | {line}" for i, line in enumerate(snippet_lines)
+        )
+
+        # Try to extract function/class context
+        function_name = None
+        class_name = None
+        try:
+            tree = ast.parse(content)
+            for node in ast.walk(tree):
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    node_start = getattr(node, "lineno", 0)
+                    node_end = getattr(node, "end_lineno", 0)
+                    if node_start <= line_number <= node_end:
+                        function_name = node.name
+                elif isinstance(node, ast.ClassDef):
+                    node_start = getattr(node, "lineno", 0)
+                    node_end = getattr(node, "end_lineno", 0)
+                    if node_start <= line_number <= node_end:
+                        class_name = node.name
+        except (SyntaxError, ValueError):
+            pass
+
+        return CodeContext(
+            file_path="",
+            line_number=line_number,
+            function_name=function_name,
+            class_name=class_name,
+            code_snippet=snippet,
+            surrounding_context="",
+        )
+
+    @staticmethod
+    def format_duplicate_message(
+        duplicate_type: str,
+        similarity: float,
+        locations: list[dict[str, str]] | list[object],
+        source_code: str,
+        *,
+        include_refactoring: bool = True,
+    ) -> str:
+        """Format an enriched duplicate detection message."""
+        # Build location summary
+        location_summary: list[str] = []
+        for loc_obj in locations:
+            # Handle both dict and TypedDict formats
+            if not isinstance(loc_obj, dict):
+                continue
+
+            loc = cast(dict[str, str], loc_obj)
+            name: str = loc.get("name", "unknown")
+            lines: str = loc.get("lines", "?")
+            loc_type: str = loc.get("type", "code")
+            location_summary.append(f"  • {name} ({loc_type}, lines {lines})")
+
+        # Determine refactoring strategy
+        # Convert locations to proper format for refactoring strategy
+        dict_locations: list[dict[str, str]] = []
+        for loc_item in locations:
+            if isinstance(loc_item, dict):
+                dict_locations.append(cast(dict[str, str], loc_item))
+
+        strategy = EnhancedMessageFormatter._suggest_refactoring_strategy(
+            duplicate_type,
+            dict_locations,
+            source_code,
+        )
+
+        # Build message
+        parts: list[str] = [
+            f"🔍 Duplicate Code Detected ({similarity:.0%} similar)",
+            "",
+            "📍 Locations:",
+        ]
+        parts.extend(location_summary)
+        parts.extend(
+            [
+                "",
+                f"📊 Pattern Type: {duplicate_type}",
+            ]
+        )
+
+        if include_refactoring and strategy:
+            parts.append("")
+            parts.append("💡 Refactoring Suggestion:")
+            parts.append(f"  Strategy: {strategy.strategy_type}")
+            parts.append(f"  {strategy.description}")
+            parts.append("")
+            parts.append("✅ Benefits:")
+            for benefit in strategy.benefits:
+                parts.append(f"  • {benefit}")
+
+            if strategy.example_before and strategy.example_after:
+                parts.append("")
+                parts.append("📝 Example:")
+                parts.append("  Before:")
+                for line in strategy.example_before.splitlines():
+                    parts.append(f"    {line}")
+                parts.append("  After:")
+                for line in strategy.example_after.splitlines():
+                    parts.append(f"    {line}")
+
+        return "\n".join(parts)
+
+    @staticmethod
+    def _suggest_refactoring_strategy(
+        duplicate_type: str,
+        locations: list[dict[str, str]],
+        _source_code: str,
+    ) -> RefactoringStrategy | None:
+        """Suggest a refactoring strategy based on duplicate characteristics."""
+        # Exact duplicates - extract function
+        if duplicate_type == "exact":
+            return RefactoringStrategy(
+                strategy_type="Extract Common Function",
+                description=(
+                    "Identical code blocks should be extracted into "
+                    "a shared function/method"
+                ),
+                example_before=textwrap.dedent("""
+                    def process_user(user):
+                        if not user.is_active:
+                            return None
+                        user.last_seen = now()
+                        return user
+
+                    def process_admin(admin):
+                        if not admin.is_active:
+                            return None
+                        admin.last_seen = now()
+                        return admin
+                """).strip(),
+                example_after=textwrap.dedent("""
+                    def update_last_seen(entity):
+                        if not entity.is_active:
+                            return None
+                        entity.last_seen = now()
+                        return entity
+
+                    def process_user(user):
+                        return update_last_seen(user)
+
+                    def process_admin(admin):
+                        return update_last_seen(admin)
+                """).strip(),
+                benefits=[
+                    "Single source of truth for the logic",
+                    "Easier to test and maintain",
+                    "Bugs fixed in one place affect all uses",
+                ],
+            )
+
+        # Structural duplicates - use inheritance or composition
+        if duplicate_type == "structural":
+            loc_types = [loc.get("type", "") for loc in locations]
+            if "class" in loc_types or "method" in loc_types:
+                return RefactoringStrategy(
+                    strategy_type="Use Inheritance or Composition",
+                    description=(
+                        "Similar structure suggests shared behavior - "
+                        "consider base class or composition"
+                    ),
+                    example_before=textwrap.dedent("""
+                        class FileProcessor:
+                            def process(self, path):
+                                self.validate(path)
+                                data = self.read(path)
+                                return self.transform(data)
+
+                        class ImageProcessor:
+                            def process(self, path):
+                                self.validate(path)
+                                data = self.read(path)
+                                return self.transform(data)
+                    """).strip(),
+                    example_after=textwrap.dedent("""
+                        class BaseProcessor:
+                            def process(self, path):
+                                self.validate(path)
+                                data = self.read(path)
+                                return self.transform(data)
+
+                            def transform(self, data):
+                                raise NotImplementedError
+
+                        class FileProcessor(BaseProcessor):
+                            def transform(self, data):
+                                return process_file(data)
+
+                        class ImageProcessor(BaseProcessor):
+                            def transform(self, data):
+                                return process_image(data)
+                    """).strip(),
+                    benefits=[
+                        "Enforces consistent interface",
+                        "Reduces code duplication",
+                        "Easier to add new processor types",
+                    ],
+                )
+
+        # Semantic duplicates - parameterize
+        if duplicate_type == "semantic":
+            return RefactoringStrategy(
+                strategy_type="Parameterize Variations",
+                description=(
+                    "Similar patterns with slight variations can be parameterized"
+                ),
+                example_before=textwrap.dedent("""
+                    def send_email_notification(user, message):
+                        send_email(user.email, message)
+                        log_notification("email", user.id)
+
+                    def send_sms_notification(user, message):
+                        send_sms(user.phone, message)
+                        log_notification("sms", user.id)
+                """).strip(),
+                example_after=textwrap.dedent("""
+                    def send_notification(user, message, method="email"):
+                        if method == "email":
+                            send_email(user.email, message)
+                        elif method == "sms":
+                            send_sms(user.phone, message)
+                        log_notification(method, user.id)
+                """).strip(),
+                benefits=[
+                    "Consolidates similar logic",
+                    "Easier to add new notification methods",
+                    "Single place to update notification logging",
+                ],
+            )
+
+        return None
+
+    @staticmethod
+    def format_type_error_message(
+        tool_name: str,
+        error_output: str,
+        source_code: str,
+    ) -> str:
+        """Format an enriched type checking error message."""
+        # Extract line numbers from error output
+        line_numbers = re.findall(r"[Ll]ine (\d+)", error_output)
+
+        parts = [
+            f"🔍 {tool_name} Type Checking Issues",
+            "",
+            error_output,
+        ]
+
+        # Add contextual guidance based on common patterns
+        if (
+            "is not defined" in error_output.lower()
+            or "cannot find" in error_output.lower()
+        ):
+            parts.extend(
+                [
+                    "",
+                    "💡 Common Fixes:",
+                    "  • Add missing import: from typing import ...",
+                    "  • Check for typos in type names",
+                    "  • Ensure type is defined before use",
+                ]
+            )
+
+        if "incompatible type" in error_output.lower():
+            parts.extend(
+                [
+                    "",
+                    "💡 Type Mismatch Guidance:",
+                    "  • Check function return type matches annotation",
+                    "  • Verify argument types match parameters",
+                    "  • Consider using Union[T1, T2] for multiple valid types",
+                    "  • Use type narrowing with isinstance() checks",
+                ]
+            )
+
+        if line_numbers:
+            parts.extend(
+                [
+                    "",
+                    "📍 Code Context:",
+                ]
+            )
+            try:
+                for line_num in line_numbers[:3]:  # Show first 3 contexts
+                    context = EnhancedMessageFormatter.extract_code_context(
+                        source_code,
+                        int(line_num),
+                        context_lines=2,
+                    )
+                    parts.append(context.code_snippet)
+                    parts.append("")
+            except (ValueError, IndexError):
+                pass
+
+        return "\n".join(parts)
+
+    @staticmethod
+    def format_complexity_message(
+        avg_complexity: float,
+        threshold: int,
+        high_count: int,
+    ) -> str:
+        """Format an enriched complexity warning message."""
+        parts = [
+            "🔍 High Code Complexity Detected",
+            "",
+            "📊 Metrics:",
+            f"  • Average Cyclomatic Complexity: {avg_complexity:.1f}",
+            f"  • Threshold: {threshold}",
+            f"  • Functions with high complexity: {high_count}",
+            "",
+            "💡 Complexity Reduction Strategies:",
+            "  • Extract nested conditions into separate functions",
+            "  • Use guard clauses to reduce nesting",
+            "  • Replace complex conditionals with polymorphism or strategy pattern",
+            "  • Break down large functions into smaller, focused ones",
+            "",
+            "📚 Why This Matters:",
+            "  • Complex code is harder to understand and maintain",
+            "  • More likely to contain bugs",
+            "  • Difficult to test thoroughly",
+            "  • Slows down development velocity",
+        ]
+
+        return "\n".join(parts)
+
+    @staticmethod
+    def format_test_quality_message(
+        rule_id: str,
+        function_name: str,
+        code_snippet: str,
+        *,
+        include_examples: bool = True,
+    ) -> str:
+        """Format an enriched test quality violation message."""
+        guidance_map = {
+            "no-conditionals-in-tests": {
+                "title": "🚫 Conditional Logic in Test",
+                "problem": (
+                    f"Test function '{function_name}' contains if/elif/else statements"
+                ),
+                "why": (
+                    "Conditionals in tests make it unclear what's being "
+                    "tested and hide failures"
+                ),
+                "fixes": [
+                    "Split into separate test functions, one per scenario",
+                    "Use @pytest.mark.parametrize for data-driven tests",
+                    "Extract conditional logic into test helpers/fixtures",
+                ],
+                "example_before": textwrap.dedent("""
+                    def test_user_access():
+                        user = create_user()
+                        if user.is_admin:
+                            assert user.can_access_admin()
+                        else:
+                            assert not user.can_access_admin()
+                """).strip(),
+                "example_after": textwrap.dedent("""
+                    @pytest.mark.parametrize('is_admin,can_access', [
+                        (True, True),
+                        (False, False)
+                    ])
+                    def test_user_access(is_admin, can_access):
+                        user = create_user(admin=is_admin)
+                        assert user.can_access_admin() == can_access
+                """).strip(),
+            },
+            "no-loop-in-tests": {
+                "title": "🚫 Loop in Test Function",
+                "problem": (
+                    f"Test function '{function_name}' contains a for/while loop"
+                ),
+                "why": (
+                    "Loops in tests hide which iteration failed and "
+                    "make debugging harder"
+                ),
+                "fixes": [
+                    "Use @pytest.mark.parametrize with test data",
+                    "Create separate test per data item",
+                    "Use pytest's subTest for dynamic test generation",
+                ],
+                "example_before": textwrap.dedent("""
+                    def test_validate_inputs():
+                        for value in [1, 2, 3, 4]:
+                            assert validate(value)
+                """).strip(),
+                "example_after": textwrap.dedent("""
+                    @pytest.mark.parametrize('value', [1, 2, 3, 4])
+                    def test_validate_inputs(value):
+                        assert validate(value)
+                """).strip(),
+            },
+            "raise-specific-error": {
+                "title": "⚠️ Generic Exception Type",
+                "problem": (
+                    f"Test function '{function_name}' raises or asserts "
+                    "generic Exception"
+                ),
+                "why": (
+                    "Specific exceptions document expected behavior and "
+                    "catch wrong error types"
+                ),
+                "fixes": [
+                    (
+                        "Replace Exception with specific type "
+                        "(ValueError, TypeError, etc.)"
+                    ),
+                    "Create custom exception classes for domain errors",
+                    "Use pytest.raises(SpecificError) in tests",
+                ],
+                "example_before": textwrap.dedent("""
+                    def process_data(value):
+                        if value < 0:
+                            raise Exception("Invalid value")
+                """).strip(),
+                "example_after": textwrap.dedent("""
+                    def process_data(value):
+                        if value < 0:
+                            raise ValueError("Value must be non-negative")
+                """).strip(),
+            },
+            "dont-import-test-modules": {
+                "title": "🚫 Production Code Imports from Tests",
+                "problem": f"File '{function_name}' imports from test modules",
+                "why": (
+                    "Production code should not depend on test helpers - "
+                    "creates circular dependencies"
+                ),
+                "fixes": [
+                    "Move shared utilities to src/utils or similar",
+                    "Create fixtures package for test data",
+                    "Use dependency injection for test doubles",
+                ],
+                "example_before": textwrap.dedent("""
+                    # src/processor.py
+                    from tests.helpers import mock_database
+                """).strip(),
+                "example_after": textwrap.dedent("""
+                    # src/utils/test_helpers.py
+                    def mock_database():
+                        ...
+
+                    # src/processor.py
+                    from src.utils.test_helpers import mock_database
+                """).strip(),
+            },
+        }
+
+        guidance = guidance_map.get(
+            rule_id,
+            {
+                "title": "⚠️ Test Quality Issue",
+                "problem": f"Issue detected in '{function_name}'",
+                "why": "Test code should be simple and focused",
+                "fixes": ["Review test structure", "Follow AAA pattern"],
+                "example_before": "",
+                "example_after": "",
+            },
+        )
+
+        parts: list[str] = [
+            str(guidance["title"]),
+            "",
+            f"📋 Problem: {guidance['problem']}",
+            "",
+            f"❓ Why This Matters: {guidance['why']}",
+            "",
+            "🛠️ How to Fix:",
+        ]
+        fixes_list = guidance["fixes"]
+        if isinstance(fixes_list, list):
+            for fix in fixes_list:
+                parts.append(f"  • {fix}")
+
+        if include_examples and guidance.get("example_before"):
+            parts.append("")
+            parts.append("💡 Example:")
+            parts.append("  ❌ Before:")
+            example_before_str = guidance.get("example_before", "")
+            if isinstance(example_before_str, str):
+                for line in example_before_str.splitlines():
+                    parts.append(f"    {line}")
+            parts.append("  ✅ After:")
+            example_after_str = guidance.get("example_after", "")
+            if isinstance(example_after_str, str):
+                for line in example_after_str.splitlines():
+                    parts.append(f"    {line}")
+
+        if code_snippet:
+            parts.append("")
+            parts.append("📍 Your Code:")
+            for line in code_snippet.splitlines()[:10]:
+                parts.append(f"  {line}")
+
+        return "\n".join(parts)
+
+    @staticmethod
+    def format_type_hint_suggestion(
+        line_number: int,
+        old_pattern: str,
+        suggested_replacement: str,
+        code_context: str,
+    ) -> str:
+        """Format a type hint modernization suggestion."""
+        parts = [
+            f"💡 Modern Typing Pattern Available (Line {line_number})",
+            "",
+            f"📋 Current: {old_pattern}",
+            f"✅ Suggested: {suggested_replacement}",
+            "",
+            "📍 Context:",
+            *[f"  {line}" for line in code_context.splitlines()],
+            "",
+            "🔗 Reference: PEP 604 (Python 3.10+) union syntax",
+        ]
+
+        return "\n".join(parts)

hooks/type_inference.py

@@ -0,0 +1,418 @@
+"""Type inference and suggestion helpers for improved hook guidance.
+
+Analyzes code to suggest specific type annotations instead of generic ones.
+"""
+
+import ast
+import re
+import textwrap
+from dataclasses import dataclass
+
+
+@dataclass
+class TypeSuggestion:
+    """A suggested type annotation for a code element."""
+
+    element_name: str
+    current_type: str
+    suggested_type: str
+    confidence: float  # 0.0 to 1.0
+    reason: str
+    example: str
+
+
+class TypeInferenceHelper:
+    """Helps infer and suggest better type annotations."""
+
+    # Common patterns and their likely types
+    PATTERN_TYPE_MAP = {
+        r"\.read\(\)": "str | bytes",
+        r"\.readlines\(\)": "list[str]",
+        r"\.split\(": "list[str]",
+        r"\.strip\(\)": "str",
+        r"\.items\(\)": "ItemsView",
+        r"\.keys\(\)": "KeysView",
+        r"\.values\(\)": "ValuesView",
+        r"json\.loads\(": "dict[str, Any]",  # Still Any but documented
+        r"json\.dumps\(": "str",
+        r"Path\(": "Path",
+        r"open\(": "TextIOWrapper | BufferedReader",
+        r"\[.*\]": "list",
+        r"\{.*:.*\}": "dict",
+        r"\{.*\}": "set",
+        r"\(.*,.*\)": "tuple",
+    }
+
+    @staticmethod
+    def infer_variable_type(
+        variable_name: str,
+        source_code: str,
+    ) -> TypeSuggestion | None:
+        """Infer the type of a variable from its usage in code."""
+        try:
+            tree = ast.parse(textwrap.dedent(source_code))
+        except SyntaxError:
+            return None
+
+        # Find assignments to this variable
+        assignments: list[ast.expr] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id == variable_name:
+                        assignments.append(node.value)
+            elif (
+                isinstance(node, ast.AnnAssign)
+                and isinstance(node.target, ast.Name)
+                and node.target.id == variable_name
+            ):
+                # Already annotated
+                return None
+
+        if not assignments:
+            return None
+
+        # Analyze the first assignment
+        value_node = assignments[0]
+        suggested_type = TypeInferenceHelper._infer_from_node(value_node)
+
+        if suggested_type and suggested_type != "Any":
+            return TypeSuggestion(
+                element_name=variable_name,
+                current_type="Any",
+                suggested_type=suggested_type,
+                confidence=0.8,
+                reason=f"Inferred from assignment: {ast.unparse(value_node)[:50]}",
+                example=f"{variable_name}: {suggested_type} = ...",
+            )
+
+        return None
+
+    @staticmethod
+    def _infer_from_node(node: ast.AST) -> str:
+        """Infer type from an AST node."""
+        if isinstance(node, ast.Constant):
+            value_type = type(node.value).__name__
+            return {
+                "NoneType": "None",
+                "bool": "bool",
+                "int": "int",
+                "float": "float",
+                "str": "str",
+                "bytes": "bytes",
+            }.get(value_type, "Any")
+
+        if isinstance(node, ast.List):
+            if not node.elts:
+                return "list[Any]"
+            # Try to infer element type from first element
+            first_type = TypeInferenceHelper._infer_from_node(node.elts[0])
+            return f"list[{first_type}]"
+
+        if isinstance(node, ast.Dict):
+            if not node.keys or not node.values:
+                return "dict[Any, Any]"
+            first_key = node.keys[0]
+            if first_key is None:
+                return "dict[Any, Any]"
+            key_type = TypeInferenceHelper._infer_from_node(first_key)
+            value_type = TypeInferenceHelper._infer_from_node(node.values[0])
+            return f"dict[{key_type}, {value_type}]"
+
+        if isinstance(node, ast.Set):
+            if not node.elts:
+                return "set[Any]"
+            element_type = TypeInferenceHelper._infer_from_node(node.elts[0])
+            return f"set[{element_type}]"
+
+        if isinstance(node, ast.Tuple):
+            if not node.elts:
+                return "tuple[()]"
+            types = [TypeInferenceHelper._infer_from_node(e) for e in node.elts]
+            return f"tuple[{', '.join(types)}]"
+
+        if isinstance(node, ast.Call):
+            func = node.func
+            if isinstance(func, ast.Name):
+                # Common constructors
+                if func.id in ("list", "dict", "set", "tuple", "str", "int", "float"):
+                    return f"{func.id}"
+                if func.id == "open":
+                    return "TextIOWrapper"
+            elif isinstance(func, ast.Attribute):
+                if func.attr == "read":
+                    return "str | bytes"
+                if func.attr == "readlines":
+                    return "list[str]"
+
+        return "Any"
+
+    @staticmethod
+    def suggest_function_return_type(
+        function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+        _source_code: str,
+    ) -> TypeSuggestion | None:
+        """Suggest return type for a function based on its return statements."""
+        # If already annotated, skip
+        if function_node.returns:
+            return None
+
+        # Find all return statements
+        return_types: set[str] = set()
+        for node in ast.walk(function_node):
+            if isinstance(node, ast.Return):
+                if node.value is None:
+                    return_types.add("None")
+                else:
+                    inferred = TypeInferenceHelper._infer_from_node(node.value)
+                    return_types.add(inferred)
+
+        if not return_types:
+            return_types.add("None")
+
+        # Combine multiple return types
+        if len(return_types) == 1:
+            suggested = return_types.pop()
+        elif "None" in return_types and len(return_types) == 2:
+            non_none = [t for t in return_types if t != "None"]
+            suggested = f"{non_none[0]} | None"
+        else:
+            suggested = " | ".join(sorted(return_types))
+
+        return TypeSuggestion(
+            element_name=function_node.name,
+            current_type="<no annotation>",
+            suggested_type=suggested,
+            confidence=0.7,
+            reason="Inferred from return statements",
+            example=f"def {function_node.name}(...) -> {suggested}:",
+        )
+
+    @staticmethod
+    def suggest_parameter_types(
+        function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+        _source_code: str,
+    ) -> list[TypeSuggestion]:
+        """Suggest types for function parameters based on their usage."""
+        suggestions = []
+
+        for arg in function_node.args.args:
+            # Skip if already annotated
+            if arg.annotation:
+                continue
+
+            # Skip self/cls
+            if arg.arg in ("self", "cls"):
+                continue
+
+            # Try to infer from usage within function
+            arg_name = arg.arg
+            suggested_type = TypeInferenceHelper._infer_param_from_usage(
+                arg_name,
+                function_node,
+            )
+
+            if suggested_type:
+                suggestions.append(
+                    TypeSuggestion(
+                        element_name=arg_name,
+                        current_type="<no annotation>",
+                        suggested_type=suggested_type,
+                        confidence=0.6,
+                        reason=f"Inferred from usage in {function_node.name}",
+                        example=f"{arg_name}: {suggested_type}",
+                    )
+                )
+
+        return suggestions
+
+    @staticmethod
+    def _infer_param_from_usage(
+        param_name: str,
+        function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> str | None:
+        """Infer parameter type from how it's used in the function."""
+        # Look for attribute access, method calls, subscripting, etc.
+        for node in ast.walk(function_node):
+            if (
+                isinstance(node, ast.Attribute)
+                and isinstance(node.value, ast.Name)
+                and node.value.id == param_name
+            ):
+                # Parameter has attribute access - likely an object
+                attr_name = node.attr
+                # Common patterns
+                if attr_name in (
+                    "read",
+                    "write",
+                    "close",
+                    "readline",
+                    "readlines",
+                ):
+                    return "TextIOWrapper | BufferedReader"
+                if attr_name in ("items", "keys", "values", "get"):
+                    return "dict[str, Any]"
+                if attr_name in ("append", "extend", "pop", "remove"):
+                    return "list[Any]"
+                if attr_name in ("add", "remove", "discard"):
+                    return "set[Any]"
+
+            if (
+                isinstance(node, ast.Subscript)
+                and isinstance(node.value, ast.Name)
+                and node.value.id == param_name
+            ):
+                # Parameter is subscripted - likely a sequence or mapping
+                return "Sequence[Any] | Mapping[str, Any]"
+
+            if (
+                isinstance(node, (ast.For, ast.AsyncFor))
+                and isinstance(node.iter, ast.Name)
+                and node.iter.id == param_name
+            ):
+                # Parameter is iterated over
+                return "Iterable[Any]"
+
+            if (
+                isinstance(node, ast.Call)
+                and isinstance(node.func, ast.Name)
+                and node.func.id == param_name
+            ):
+                # Check if param is called (callable)
+                return "Callable[..., Any]"
+
+        return None
+
+    @staticmethod
+    def modernize_typing_imports(source_code: str) -> list[tuple[str, str, str]]:
+        """Find old typing imports and suggest modern alternatives.
+
+        Returns list of (old_import, new_import, reason) tuples.
+        """
+        suggestions = []
+
+        # Patterns to detect and replace
+        patterns = {
+            r"from typing import.*\bUnion\b": (
+                "from typing import Union",
+                "# Use | operator instead (Python 3.10+)",
+                "Union[str, int] → str | int",
+            ),
+            r"from typing import.*\bOptional\b": (
+                "from typing import Optional",
+                "# Use | None instead (Python 3.10+)",
+                "Optional[str] → str | None",
+            ),
+            r"from typing import.*\bList\b": (
+                "from typing import List",
+                "# Use built-in list (Python 3.9+)",
+                "List[str] → list[str]",
+            ),
+            r"from typing import.*\bDict\b": (
+                "from typing import Dict",
+                "# Use built-in dict (Python 3.9+)",
+                "Dict[str, int] → dict[str, int]",
+            ),
+            r"from typing import.*\bSet\b": (
+                "from typing import Set",
+                "# Use built-in set (Python 3.9+)",
+                "Set[str] → set[str]",
+            ),
+            r"from typing import.*\bTuple\b": (
+                "from typing import Tuple",
+                "# Use built-in tuple (Python 3.9+)",
+                "Tuple[str, int] → tuple[str, int]",
+            ),
+        }
+
+        for pattern, (old, new, example) in patterns.items():
+            if re.search(pattern, source_code):
+                suggestions.append((old, new, example))
+
+        return suggestions
+
+    @staticmethod
+    def find_any_usage_with_context(source_code: str) -> list[dict[str, str | int]]:
+        """Find usage of typing.Any and provide context for better suggestions."""
+        results = []
+
+        try:
+            tree = ast.parse(textwrap.dedent(source_code))
+        except SyntaxError:
+            return results
+
+        for node in ast.walk(tree):
+            # Find variable annotations with Any
+            if isinstance(node, ast.AnnAssign) and TypeInferenceHelper._contains_any(
+                node.annotation
+            ):
+                target_name = ""
+                if isinstance(node.target, ast.Name):
+                    target_name = node.target.id
+
+                # Try to infer better type from value
+                better_type = "Any"
+                if node.value:
+                    better_type = TypeInferenceHelper._infer_from_node(node.value)
+
+                results.append(
+                    {
+                        "line": getattr(node, "lineno", 0),
+                        "element": target_name,
+                        "current": "Any",
+                        "suggested": better_type,
+                        "context": "variable annotation",
+                    }
+                )
+
+            # Find function parameters with Any
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                for arg in node.args.args:
+                    if arg.annotation and TypeInferenceHelper._contains_any(
+                        arg.annotation
+                    ):
+                        results.append(
+                            {
+                                "line": getattr(node, "lineno", 0),
+                                "element": arg.arg,
+                                "current": "Any",
+                                "suggested": "Infer from usage",
+                                "context": f"parameter in {node.name}",
+                            }
+                        )
+
+                # Check return type
+                if node.returns and TypeInferenceHelper._contains_any(node.returns):
+                    suggestion = TypeInferenceHelper.suggest_function_return_type(
+                        node,
+                        source_code
+                    )
+                    suggested_type = suggestion.suggested_type if suggestion else "Any"
+                    results.append(
+                        {
+                            "line": getattr(node, "lineno", 0),
+                            "element": node.name,
+                            "current": "Any",
+                            "suggested": suggested_type,
+                            "context": "return type",
+                        }
+                    )
+
+        return results
+
+    @staticmethod
+    def _contains_any(annotation: ast.AST) -> bool:
+        """Check if an annotation contains typing.Any."""
+        if isinstance(annotation, ast.Name) and annotation.id == "Any":
+            return True
+        if isinstance(annotation, ast.Attribute) and annotation.attr == "Any":
+            return True
+        # Check subscripts like list[Any]
+        if isinstance(annotation, ast.Subscript):
+            return TypeInferenceHelper._contains_any(annotation.slice)
+        # Check unions
+        if isinstance(annotation, ast.BinOp):
+            return TypeInferenceHelper._contains_any(
+                annotation.left,
+            ) or TypeInferenceHelper._contains_any(annotation.right)
+        return False

pyproject.toml

@@ -30,6 +30,7 @@ dependencies = [
     "tomli>=2.0.0; python_version < '3.11'",
     "python-Levenshtein>=0.20.0",
     "datasketch>=1.5.0",
+    "bandit>=1.8.6",
 ]
 
 [project.optional-dependencies]
@@ -147,6 +148,13 @@ exclude_lines = [
     "except ImportError:",
 ]
 
+[tool.basedpyright]
+include = ["src", "hooks", "tests"]
+extraPaths = ["hooks"]
+pythonVersion = "3.12"
+typeCheckingMode = "standard"
+reportMissingTypeStubs = false
+
 [dependency-groups]
 dev = [
     "sourcery>=1.37.0",

pyrightconfig.json

@@ -0,0 +1,9 @@
+{
+  "venvPath": ".",
+  "venv": ".venv",
+  "pythonVersion": "3.12",
+  "typeCheckingMode": "basic",
+  "reportMissingImports": true,
+  "reportMissingTypeStubs": false,
+  "reportMissingModuleSource": "warning"
+}

src/quality/cli/main.py

@@ -478,10 +478,8 @@ def _print_console_duplicates(results: dict[str, Any], verbose: bool) -> None:
 
 def _print_csv_duplicates(results: dict[str, Any], output: IO[str] | None) -> None:
     """Print duplicate results in CSV format."""
-    if not output:
-        output = sys.stdout
-
-    writer = csv.writer(output)
+    csv_output = output if output else sys.stdout
+    writer = csv.writer(csv_output)
     writer.writerow(
         [
             "Group ID",

src/quality/complexity/analyzer.py

@@ -79,15 +79,19 @@ class ComplexityAnalyzer:
 
         # Add summary information
         if "file_metrics" in report:
-            metrics = ComplexityMetrics.from_dict(report["file_metrics"])
+            file_metrics = report["file_metrics"]
+            assert isinstance(file_metrics, dict), "file_metrics must be dict"
+            metrics = ComplexityMetrics.from_dict(file_metrics)
             report["summary"] = self.get_complexity_summary(metrics)
 
         # Filter functions and classes that exceed thresholds
         if "functions" in report:
+            functions = report["functions"]
+            assert isinstance(functions, list), "functions must be list"
             report["high_complexity_functions"] = [
                 func
-                for func in report["functions"]
-                if func["complexity"] >= self.config.complexity_threshold
+                for func in functions
+                if isinstance(func, dict) and func.get("complexity", 0) >= self.config.complexity_threshold
             ]
 
         return report

src/quality/complexity/radon_integration.py

@@ -2,16 +2,16 @@
 
 import ast
 from pathlib import Path
-from typing import Any
 
+RADON_AVAILABLE = False
 try:
-    from radon.complexity import cc_rank, cc_visit
-    from radon.metrics import h_visit, mi_visit
-    from radon.raw import analyze
+    import radon.complexity
+    import radon.metrics
+    import radon.raw
 
     RADON_AVAILABLE = True
 except ImportError:
-    RADON_AVAILABLE = False
+    pass
 
 from .calculator import ComplexityCalculator
 from .metrics import ComplexityMetrics
@@ -48,47 +48,65 @@ class RadonComplexityAnalyzer:
         metrics = ComplexityMetrics()
 
         try:
+            import radon.raw
+
             # Raw metrics (lines of code, etc.)
-            raw_metrics = analyze(code)
-            if raw_metrics:
-                metrics.lines_of_code = raw_metrics.loc
-                metrics.logical_lines_of_code = raw_metrics.lloc
-                metrics.source_lines_of_code = raw_metrics.sloc
-                metrics.comment_lines = raw_metrics.comments
-                metrics.blank_lines = raw_metrics.blank
+            raw_metrics = radon.raw.analyze(code)
+            if raw_metrics and hasattr(raw_metrics, "loc"):
+                metrics.lines_of_code = getattr(raw_metrics, "loc", 0)
+                metrics.logical_lines_of_code = getattr(raw_metrics, "lloc", 0)
+                metrics.source_lines_of_code = getattr(raw_metrics, "sloc", 0)
+                metrics.comment_lines = getattr(raw_metrics, "comments", 0)
+                metrics.blank_lines = getattr(raw_metrics, "blank", 0)
+
+            import radon.complexity
 
             # Cyclomatic complexity
-            cc_results = cc_visit(code)
+            cc_results = radon.complexity.cc_visit(code)
             if cc_results:
-                # Sum up complexity from all functions/methods
-                total_complexity = sum(block.complexity for block in cc_results)
-                metrics.cyclomatic_complexity = total_complexity
+                # Calculate average complexity from all functions/methods
+                total_complexity = sum(
+                    getattr(block, "complexity", 0) for block in cc_results
+                )
+                # Average complexity = total / number of blocks
+                metrics.cyclomatic_complexity = (
+                    total_complexity / len(cc_results) if cc_results else 0.0
+                )
 
                 # Count functions and classes
-                metrics.function_count = len(
-                    [b for b in cc_results if b.is_method or b.type == "function"],
-                )
-                metrics.class_count = len([b for b in cc_results if b.type == "class"])
-                metrics.method_count = len([b for b in cc_results if b.is_method])
+                metrics.function_count = len([
+                    b for b in cc_results
+                    if getattr(b, "is_method", False) or getattr(b, "type", "") == "function"
+                ])
+                metrics.class_count = len([
+                    b for b in cc_results if getattr(b, "type", "") == "class"
+                ])
+                metrics.method_count = len([
+                    b for b in cc_results if getattr(b, "is_method", False)
+                ])
 
             # Halstead metrics
             try:
-                halstead_data = h_visit(code)
-                if halstead_data:
-                    metrics.halstead_difficulty = halstead_data.difficulty
-                    metrics.halstead_effort = halstead_data.effort
-                    metrics.halstead_volume = halstead_data.volume
-                    metrics.halstead_time = halstead_data.time
-                    metrics.halstead_bugs = halstead_data.bugs
+                import radon.metrics
+
+                halstead_data = radon.metrics.h_visit(code)
+                if halstead_data and hasattr(halstead_data, "difficulty"):
+                    metrics.halstead_difficulty = getattr(halstead_data, "difficulty", 0.0)
+                    metrics.halstead_effort = getattr(halstead_data, "effort", 0.0)
+                    metrics.halstead_volume = getattr(halstead_data, "volume", 0.0)
+                    metrics.halstead_time = getattr(halstead_data, "time", 0.0)
+                    metrics.halstead_bugs = getattr(halstead_data, "bugs", 0.0)
             except (ValueError, TypeError, AttributeError):
                 # Halstead calculation can fail for some code patterns
                 pass
 
             # Maintainability Index
             try:
-                mi_data = mi_visit(code, multi=True)
+                import radon.metrics
+
+                mi_data = radon.metrics.mi_visit(code, multi=True)
                 if mi_data and hasattr(mi_data, "mi"):
-                    metrics.maintainability_index = mi_data.mi
+                    metrics.maintainability_index = getattr(mi_data, "mi", 0.0)
             except (ValueError, TypeError, AttributeError):
                 # MI calculation can fail, calculate manually
                 metrics.maintainability_index = self._calculate_mi_fallback(metrics)
@@ -252,7 +270,20 @@ class RadonComplexityAnalyzer:
                 return "D"  # Very High
             return "F"  # Extreme
 
-        return str(cc_rank(complexity_score))
+        if RADON_AVAILABLE:
+            import radon.complexity
+
+            return str(radon.complexity.cc_rank(complexity_score))
+        # Fallback if radon not available
+        if complexity_score <= 5:
+            return "A"
+        if complexity_score <= 10:
+            return "B"
+        if complexity_score <= 20:
+            return "C"
+        if complexity_score <= 30:
+            return "D"
+        return "F"
 
     def batch_analyze_files(
         self,
@@ -289,7 +320,7 @@ class RadonComplexityAnalyzer:
         self,
         code: str,
         filename: str = "<string>",
-    ) -> dict[str, Any]:
+    ) -> dict[str, object]:
         """Get detailed complexity report including function-level analysis."""
         if not RADON_AVAILABLE:
             metrics = self.manual_calculator.calculate_complexity(code)
@@ -307,21 +338,24 @@ class RadonComplexityAnalyzer:
         classes = []
 
         try:
-            cc_results = cc_visit(code)
+            import radon.complexity
+
+            cc_results = radon.complexity.cc_visit(code)
             for block in cc_results:
                 item = {
-                    "name": block.name,
-                    "complexity": block.complexity,
-                    "rank": self.get_complexity_rank(block.complexity),
-                    "line_number": block.lineno,
+                    "name": getattr(block, "name", ""),
+                    "complexity": getattr(block, "complexity", 0),
+                    "rank": self.get_complexity_rank(getattr(block, "complexity", 0)),
+                    "line_number": getattr(block, "lineno", 0),
                     "end_line": getattr(block, "endline", None),
-                    "type": block.type,
+                    "type": getattr(block, "type", ""),
                     "is_method": getattr(block, "is_method", False),
                 }
 
-                if block.type == "function" or getattr(block, "is_method", False):
+                block_type = getattr(block, "type", "")
+                if block_type == "function" or getattr(block, "is_method", False):
                     functions.append(item)
-                elif block.type == "class":
+                elif block_type == "class":
                     classes.append(item)
         except (ValueError, TypeError, AttributeError):
             pass

src/quality/config/schemas.py

@@ -1,10 +1,16 @@
 """Configuration schemas using Pydantic."""
 
+from __future__ import annotations
+
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import yaml
 from pydantic import BaseModel, Field, field_validator
 
+if TYPE_CHECKING:
+    from types import ModuleType
+
 
 class SimilarityAlgorithmConfig(BaseModel):
     """Configuration for similarity algorithms."""
@@ -200,14 +206,15 @@ class QualityConfig(BaseModel):
     verbose: bool = False
 
     @field_validator("detection")
-    def validate_similarity_weights(self, v: DetectionConfig) -> DetectionConfig:
+    @classmethod
+    def validate_similarity_weights(cls, v: DetectionConfig) -> DetectionConfig:
         """Ensure similarity algorithm weights sum to approximately 1.0."""
         total_weight = sum(alg.weight for alg in v.similarity_algorithms if alg.enabled)
         if abs(total_weight - 1.0) > 0.1:
             # Auto-normalize weights
             for alg in v.similarity_algorithms:
                 if alg.enabled:
-                    alg.weight = alg.weight / total_weight
+                    alg.weight /= total_weight
         return v
 
     class Config:
@@ -241,7 +248,7 @@ def load_config(config_path: Path | None = None) -> QualityConfig:
 
 def _load_from_file(config_path: Path) -> QualityConfig:
     """Load configuration from specific file."""
-    if config_path.suffix.lower() in [".yaml", ".yml"]:
+    if config_path.suffix.lower() in {".yaml", ".yml"}:
         return _load_from_yaml(config_path)
     if config_path.name == "pyproject.toml":
         return _load_from_pyproject(config_path)
@@ -259,11 +266,14 @@ def _load_from_yaml(config_path: Path) -> QualityConfig:
 
 def _load_from_pyproject(config_path: Path) -> QualityConfig:
     """Load configuration from pyproject.toml file."""
+    toml_loader: ModuleType
     try:
-        import tomllib as tomli  # Python 3.11+
+        import tomllib  # Python 3.11+
+        toml_loader = tomllib
     except ImportError:
         try:
-            import tomli  # type: ignore[import-not-found, no-redef]
+            import tomli
+            toml_loader = tomli
         except ImportError as e:
             msg = (
                 "tomli package required to read pyproject.toml. "
@@ -274,7 +284,7 @@ def _load_from_pyproject(config_path: Path) -> QualityConfig:
             ) from e
 
     with open(config_path, "rb") as f:
-        data = tomli.load(f)
+        data = toml_loader.load(f)
 
     # Extract quality configuration
     quality_config = data.get("tool", {}).get("quality", {})

src/quality/similarity/lsh.py

@@ -2,15 +2,62 @@
 
 import hashlib
 from collections import defaultdict
-from typing import Any
+from typing import Protocol
+
+
+class MinHashProtocol(Protocol):
+    """Protocol for MinHash interface."""
+
+    num_perm: int
+
+    def update(self, data: bytes) -> None: ...
+    def jaccard(self, other: "MinHashProtocol") -> float: ...
+
+
+class MinHashLSHProtocol(Protocol):
+    """Protocol for MinHashLSH interface."""
+
+    threshold: float
+    num_perm: int
+
+    def insert(self, key: str, minhash: MinHashProtocol) -> None: ...
+    def query(self, minhash: MinHashProtocol) -> list[str]: ...
+
 
 try:
-    from datasketch import MinHash, MinHashLSH  # type: ignore[import-not-found]
+    from datasketch import MinHash, MinHashLSH
 
     LSH_AVAILABLE = True
 except ImportError:
     LSH_AVAILABLE = False
 
+    class MinHash:
+        """Dummy MinHash when datasketch unavailable."""
+
+        def __init__(self, num_perm: int = 128):
+            self.num_perm = num_perm
+
+        def update(self, data: bytes) -> None:  # noqa: ARG002
+            """Update MinHash."""
+
+        def jaccard(self, other: MinHashProtocol) -> float:  # noqa: ARG002
+            """Calculate Jaccard similarity."""
+            return 0.0
+
+    class MinHashLSH:
+        """Dummy MinHashLSH when datasketch unavailable."""
+
+        def __init__(self, threshold: float = 0.5, num_perm: int = 128):
+            self.threshold = threshold
+            self.num_perm = num_perm
+
+        def insert(self, key: str, minhash: MinHashProtocol) -> None:  # noqa: ARG002
+            """Insert MinHash."""
+
+        def query(self, minhash: MinHashProtocol) -> list[str]:  # noqa: ARG002
+            """Query similar items."""
+            return []
+
 from ..config.schemas import SimilarityAlgorithmConfig
 from ..core.base import CodeBlock
 from .base import BaseSimilarityAlgorithm
@@ -35,8 +82,8 @@ class LSHSimilarity(BaseSimilarityAlgorithm):
         self.rows = self.config.parameters.get("rows", 8)
 
         # Initialize LSH index
-        self.lsh_index = None
-        self.minhashes: dict[str, Any] = {}
+        self.lsh_index: MinHashLSH | None = None
+        self.minhashes: dict[str, MinHash] = {}
 
         if LSH_AVAILABLE:
             self._initialize_lsh()
@@ -45,8 +92,8 @@ class LSHSimilarity(BaseSimilarityAlgorithm):
         """Initialize LSH index."""
         if LSH_AVAILABLE:
             self.lsh_index = MinHashLSH(
-                threshold=self.threshold,
-                num_perm=self.num_perm,
+                threshold=float(self.threshold),
+                num_perm=int(self.num_perm),
             )
 
     def calculate(self, text1: str, text2: str) -> float:
@@ -63,14 +110,17 @@ class LSHSimilarity(BaseSimilarityAlgorithm):
         minhash1 = self._create_minhash(text1)
         minhash2 = self._create_minhash(text2)
 
+        if minhash1 is None or minhash2 is None:
+            return 0.0
+
         return float(minhash1.jaccard(minhash2))
 
-    def _create_minhash(self, text: str) -> Any:  # noqa: ANN401
+    def _create_minhash(self, text: str) -> MinHash | None:
         """Create MinHash for text."""
         if not LSH_AVAILABLE:
             return None
 
-        minhash = MinHash(num_perm=self.num_perm)
+        minhash = MinHash(num_perm=int(self.num_perm))
 
         # Create shingles from text
         shingles = self._get_shingles(text)
@@ -128,11 +178,11 @@ class LSHDuplicateDetector:
         self.rows = rows
 
         self.lsh_index = None
-        self.minhashes: dict[str, Any] = {}
+        self.minhashes: dict[str, MinHash] = {}
         self.code_blocks: dict[str, CodeBlock] = {}
 
         if LSH_AVAILABLE:
-            self.lsh_index = MinHashLSH(threshold=threshold, num_perm=num_perm)
+            self.lsh_index = MinHashLSH(threshold=float(threshold), num_perm=int(num_perm))
 
     def add_code_block(self, block: CodeBlock) -> None:
         """Add a code block to the LSH index."""
@@ -142,6 +192,9 @@ class LSHDuplicateDetector:
         block_id = self._get_block_id(block)
         minhash = self._create_minhash(block.normalized_content)
 
+        if minhash is None:
+            return
+
         self.minhashes[block_id] = minhash
         self.code_blocks[block_id] = block
 
@@ -156,6 +209,9 @@ class LSHDuplicateDetector:
         block_id = self._get_block_id(block)
         query_minhash = self._create_minhash(block.normalized_content)
 
+        if query_minhash is None:
+            return []
+
         # Get candidate similar blocks
         candidates = self.lsh_index.query(query_minhash)
 
@@ -204,7 +260,7 @@ class LSHDuplicateDetector:
 
         return duplicate_groups
 
-    def get_statistics(self) -> dict[str, Any]:
+    def get_statistics(self) -> dict[str, object]:
         """Get LSH index statistics."""
         if not LSH_AVAILABLE or not self.lsh_index:
             return {"error": "LSH not available"}
@@ -214,17 +270,15 @@ class LSHDuplicateDetector:
             "threshold": self.threshold,
             "num_perm": self.num_perm,
             "lsh_available": LSH_AVAILABLE,
-            "index_keys": len(self.lsh_index.keys)
-            if hasattr(self.lsh_index, "keys")
-            else 0,
+            "index_keys": len(getattr(self.lsh_index, "keys", [])),
         }
 
-    def _create_minhash(self, text: str) -> Any:  # noqa: ANN401
+    def _create_minhash(self, text: str) -> MinHash | None:
         """Create MinHash for text."""
         if not LSH_AVAILABLE:
             return None
 
-        minhash = MinHash(num_perm=self.num_perm)
+        minhash = MinHash(num_perm=int(self.num_perm))
 
         # Create token-based shingles
         shingles = self._get_token_shingles(text)
@@ -313,7 +367,7 @@ class BandingLSH:
         matches = sum(1 for a, b in zip(sig1, sig2, strict=False) if a == b)
         return matches / len(sig1)
 
-    def get_statistics(self) -> dict[str, Any]:
+    def get_statistics(self) -> dict[str, object]:
         """Get LSH statistics."""
         total_buckets = sum(len(table) for table in self.hash_tables)
         avg_bucket_size = total_buckets / self.bands if self.bands > 0 else 0

src/quality/similarity/text_based.py

@@ -3,12 +3,16 @@
 import difflib
 
 try:
-    from Levenshtein import ratio as levenshtein_ratio  # type: ignore[import-not-found]
+    from Levenshtein import ratio as levenshtein_ratio
 
     LEVENSHTEIN_AVAILABLE = True
 except ImportError:
     LEVENSHTEIN_AVAILABLE = False
 
+    def levenshtein_ratio(s1: str, s2: str) -> float:
+        """Dummy levenshtein_ratio when Levenshtein unavailable."""
+        return difflib.SequenceMatcher(None, s1, s2).ratio()
+
 from ..config.schemas import SimilarityAlgorithmConfig
 from .base import BaseSimilarityAlgorithm
 

test_any_should_block.py

@@ -1,10 +0,0 @@
-"""Fixture module used to verify Any detection in the guard."""
-
-# ruff: noqa: ANN401  # These annotations intentionally use Any for the test harness.
-
-from typing import Any
-
-
-def process_data(data: Any) -> Any:
-    """Return the provided value; the guard should block this in practice."""
-    return data

test_core_hooks.py

@@ -1,131 +0,0 @@
-"""Core coverage tests for the code quality guard hooks."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any
-
-import pytest
-
-from hooks.code_quality_guard import QualityConfig, pretooluse_hook
-
-
-@pytest.fixture
-def strict_config() -> QualityConfig:
-    """Return a strict enforcement configuration for the guard."""
-    config = QualityConfig.from_env()
-    config.enforcement_mode = "strict"
-    return config
-
-
-@dataclass(slots=True)
-class BlockingScenario:
-    """Parameters describing an expected blocking outcome."""
-
-    name: str
-    tool_name: str
-    tool_input: dict[str, Any]
-    reason_fragment: str
-
-
-BLOCKING_SCENARIOS: tuple[BlockingScenario, ...] = (
-    BlockingScenario(
-        name="typing-any",
-        tool_name="Write",
-        tool_input={
-            "file_path": "/src/production.py",
-            "content": (
-                "from typing import Any\n"
-                "def bad(value: Any) -> Any:\n"
-                "    return value\n"
-            ),
-        },
-        reason_fragment="typing.Any usage",
-    ),
-    BlockingScenario(
-        name="type-ignore",
-        tool_name="Write",
-        tool_input={
-            "file_path": "/src/production.py",
-            "content": (
-                "def bad() -> None:\n"
-                "    value = call()  # type: ignore\n"
-                "    return value\n"
-            ),
-        },
-        reason_fragment="type: ignore",
-    ),
-    BlockingScenario(
-        name="legacy-typing",
-        tool_name="Write",
-        tool_input={
-            "file_path": "/src/production.py",
-            "content": (
-                "from typing import Optional, Union\n"
-                "def bad(value: Union[str, int]) -> Optional[str]:\n"
-                "    return None\n"
-            ),
-        },
-        reason_fragment="Old typing pattern",
-    ),
-    BlockingScenario(
-        name="edit-tool-any",
-        tool_name="Edit",
-        tool_input={
-            "file_path": "/src/production.py",
-            "old_string": "def old():\n    return 1\n",
-            "new_string": "def new(value: Any) -> Any:\n    return value\n",
-        },
-        reason_fragment="typing.Any usage",
-    ),
-)
-
-
-@pytest.mark.parametrize(
-    "scenario",
-    BLOCKING_SCENARIOS,
-    ids=lambda scenario: scenario.name,
-)
-def test_pretooluse_blocks_expected_patterns(
-    strict_config: QualityConfig,
-    scenario: BlockingScenario,
-) -> None:
-    """Verify the guard blocks known bad patterns."""
-    hook_data = {"tool_name": scenario.tool_name, "tool_input": scenario.tool_input}
-    result = pretooluse_hook(hook_data, strict_config)
-
-    assert result["permissionDecision"] == "deny"
-    assert scenario.reason_fragment in result.get("reason", "")
-
-
-def test_pretooluse_allows_modern_code(strict_config: QualityConfig) -> None:
-    """PreToolUse hook allows well-typed Python content."""
-    hook_data = {
-        "tool_name": "Write",
-        "tool_input": {
-            "file_path": "/src/production.py",
-            "content": (
-                "def good(value: str | int) -> str | None:\n"
-                "    return str(value) if value else None\n"
-            ),
-        },
-    }
-
-    result = pretooluse_hook(hook_data, strict_config)
-
-    assert result["permissionDecision"] == "allow"
-
-
-def test_pretooluse_allows_non_python_files(strict_config: QualityConfig) -> None:
-    """Non-Python files should bypass quality restrictions."""
-    hook_data = {
-        "tool_name": "Write",
-        "tool_input": {
-            "file_path": "/src/config.json",
-            "content": '{"type": "Any", "ignore": true}',
-        },
-    }
-
-    result = pretooluse_hook(hook_data, strict_config)
-
-    assert result["permissionDecision"] == "allow"

test_type_ignore.py

@@ -1,15 +0,0 @@
-"""Fixture module used to check handling of type: ignore annotations."""
-
-from __future__ import annotations
-
-
-def bad_function() -> int:
-    """Return a value while suppressing a typing error."""
-    x = "string"
-    return x + 5  # type: ignore[arg-type]
-
-
-def another_bad() -> int:
-    """Return a value after an ignored assignment mismatch."""
-    y: int = "not an int"  # type: ignore[assignment]
-    return y

tests/hooks/test_dynamic_usage.py

@@ -204,10 +204,14 @@ def alpha():
     )
 
     assert response_a_post.get("decision") == "block"
-    assert "Reduced functions" in response_a_post.get("reason", "")
+    reason_a = response_a_post.get("reason", "")
+    assert isinstance(reason_a, str)
+    assert "Reduced functions" in reason_a
     # Ensure the second container is unaffected by the first one's regression.
     assert response_b_post.get("decision") is None
-    assert "Reduced functions" not in response_b_post.get("reason", "")
+    reason_b = response_b_post.get("reason", "")
+    assert isinstance(reason_b, str)
+    assert "Reduced functions" not in reason_b
 
 
 def test_state_tracking_id_collision_different_paths(tmp_path: Path) -> None:
@@ -284,9 +288,13 @@ def alpha():
     )
 
     assert degraded_response.get("decision") == "block"
-    assert "Reduced functions" in degraded_response.get("reason", "")
+    reason_degraded = degraded_response.get("reason", "")
+    assert isinstance(reason_degraded, str)
+    assert "Reduced functions" in reason_degraded
     assert preserved_response.get("decision") is None
-    assert "Reduced functions" not in preserved_response.get("reason", "")
+    reason_preserved = preserved_response.get("reason", "")
+    assert isinstance(reason_preserved, str)
+    assert "Reduced functions" not in reason_preserved
 
 
 @pytest.mark.parametrize("project_marker", [".git", "pyproject.toml"])
@@ -328,11 +336,15 @@ def test_cross_file_duplicate_project_root_detection(
             config,
         )
 
-    assert "duplicates" in captured["cmd"]
-    dup_index = captured["cmd"].index("duplicates")
-    assert captured["cmd"][dup_index + 1] == str(project_root)
-    assert "--threshold" in captured["cmd"]
-    assert response["hookSpecificOutput"]["hookEventName"] == "PostToolUse"
+    cmd = captured.get("cmd", [])
+    assert isinstance(cmd, list)
+    assert "duplicates" in cmd
+    dup_index = cmd.index("duplicates")
+    assert cmd[dup_index + 1] == str(project_root)
+    assert "--threshold" in cmd
+    hook_output = response.get("hookSpecificOutput", {})
+    assert isinstance(hook_output, dict)
+    assert hook_output.get("hookEventName") == "PostToolUse"
     assert response.get("decision") is None
 
 

tests/hooks/test_edge_cases.py

@@ -93,7 +93,11 @@ def broken_func(
         decision = _perm(result)
         assert decision in ["allow", "deny", "ask"]
         if decision != "allow":
-            text = (result.get("reason") or "") + (result.get("systemMessage") or "")
+            reason = result.get("reason") or ""
+            system_msg = result.get("systemMessage") or ""
+            assert isinstance(reason, str)
+            assert isinstance(system_msg, str)
+            text = reason + system_msg
             assert "error" in text.lower()
 
     def test_unicode_content(self):

tests/hooks/test_helper_functions.py

@@ -7,10 +7,12 @@ import sys
 import tempfile
 from datetime import UTC, datetime
 from pathlib import Path
+from typing import cast
 from unittest.mock import MagicMock, patch
 
 import pytest
 from code_quality_guard import (
+    AnalysisResults,
     QualityConfig,
     analyze_code_quality,
     check_code_issues,
@@ -395,58 +397,67 @@ class TestHelperFunctions:
     def test_check_code_issues_internal_duplicates(self):
         """Test issue detection for internal duplicates."""
         config = QualityConfig()
-        results = {
-            "internal_duplicates": {
-                "duplicates": [
-                    {
-                        "similarity": 0.95,
-                        "description": "Similar functions",
-                        "locations": [
-                            {"name": "func1", "lines": "1-5"},
-                            {"name": "func2", "lines": "7-11"},
-                        ],
-                    },
-                ],
+        results = cast(
+            AnalysisResults,
+            {
+                "internal_duplicates": {
+                    "duplicates": [
+                        {
+                            "similarity": 0.95,
+                            "description": "Similar functions",
+                            "locations": [
+                                {"name": "func1", "lines": "1-5"},
+                                {"name": "func2", "lines": "7-11"},
+                            ],
+                        },
+                    ],
+                },
             },
-        }
+        )
 
         has_issues, issues = check_code_issues(results, config)
 
         assert has_issues is True
         assert len(issues) > 0
-        assert "Internal duplication" in issues[0]
+        assert "Duplicate Code Detected" in issues[0]
         assert "95%" in issues[0]
 
     def test_check_code_issues_complexity(self):
         """Test issue detection for complexity."""
         config = QualityConfig(complexity_threshold=10)
-        results = {
-            "complexity": {
-                "summary": {"average_cyclomatic_complexity": 15},
-                "distribution": {"High": 2, "Very High": 1},
+        results = cast(
+            AnalysisResults,
+            {
+                "complexity": {
+                    "summary": {"average_cyclomatic_complexity": 15},
+                    "distribution": {"High": 2, "Very High": 1},
+                },
             },
-        }
+        )
 
         has_issues, issues = check_code_issues(results, config)
 
         assert has_issues is True
-        assert any("High average complexity" in issue for issue in issues)
-        assert any("3 function(s) with high complexity" in issue for issue in issues)
+        assert any("High Code Complexity Detected" in issue for issue in issues)
+        assert any("3" in issue for issue in issues)
 
     def test_check_code_issues_modernization(self):
         """Test issue detection for modernization."""
         config = QualityConfig(require_type_hints=True)
-        results = {
-            "modernization": {
-                "files": {
-                    "test.py": [
-                        {"issue_type": "use_enumerate"},
-                        {"issue_type": "missing_return_type"},
-                        {"issue_type": "missing_param_type"},
-                    ],
+        results = cast(
+            AnalysisResults,
+            {
+                "modernization": {
+                    "files": {
+                        "test.py": [
+                            {"issue_type": "use_enumerate"},
+                            {"issue_type": "missing_return_type"},
+                            {"issue_type": "missing_param_type"},
+                        ],
+                    },
                 },
             },
-        }
+        )
 
         has_issues, issues = check_code_issues(results, config)
 
@@ -460,11 +471,14 @@ class TestHelperFunctions:
         # Create 15 type hint issues
         type_issues = [{"issue_type": "missing_return_type"} for _ in range(15)]
 
-        results = {
-            "modernization": {
-                "files": {"test.py": type_issues},
+        results = cast(
+            AnalysisResults,
+            {
+                "modernization": {
+                    "files": {"test.py": type_issues},
+                },
             },
-        }
+        )
 
         has_issues, issues = check_code_issues(results, config)
 
@@ -475,7 +489,7 @@ class TestHelperFunctions:
     def test_check_code_issues_no_issues(self):
         """Test when no issues are found."""
         config = QualityConfig()
-        results = {}
+        results = cast(AnalysisResults, {})
 
         has_issues, issues = check_code_issues(results, config)
 

tests/hooks/test_posttooluse.py

@@ -18,7 +18,10 @@ class TestPostToolUseHook:
         }
 
         result = posttooluse_hook(hook_data, config)
-        assert result["hookSpecificOutput"]["hookEventName"] == "PostToolUse"
+        assert isinstance(result, dict)
+        hook_output = result.get("hookSpecificOutput", {})
+        assert isinstance(hook_output, dict)
+        assert hook_output.get("hookEventName") == "PostToolUse"
         assert "decision" not in result
 
     def test_file_path_extraction_dict(self):
@@ -59,13 +62,16 @@ class TestPostToolUseHook:
             with patch("pathlib.Path.read_text", return_value=clean_code):
                 result = posttooluse_hook(hook_data, config)
 
-        assert result["decision"] == "approve"
-        assert "post-write verification" in result["systemMessage"].lower()
+        assert isinstance(result, dict)
+        assert result.get("decision") == "approve"
+        system_msg = result.get("systemMessage", "")
+        assert isinstance(system_msg, str)
+        assert "post-write verification" in system_msg.lower()
 
     def test_file_path_extraction_string(self):
         """Test file path extraction from string output."""
         config = QualityConfig()
-        hook_data = {
+        hook_data: dict[str, object] = {
             "tool_name": "Write",
             "tool_output": "File written successfully: /tmp/test.py",
         }
@@ -115,8 +121,11 @@ class TestPostToolUseHook:
                     ]
 
                     result = posttooluse_hook(hook_data, config)
-                    assert result["decision"] == "block"
-                    reason_text = result["reason"].lower()
+                    assert isinstance(result, dict)
+                    assert result.get("decision") == "block"
+                    reason = result.get("reason", "")
+                    assert isinstance(reason, str)
+                    reason_text = reason.lower()
                     assert "post-write quality notes" in reason_text
                     assert "reduced functions" in reason_text
 
@@ -136,8 +145,11 @@ class TestPostToolUseHook:
                     mock_check.return_value = ["⚠️ Cross-file duplication detected"]
 
                     result = posttooluse_hook(hook_data, config)
-                    assert result["decision"] == "block"
-                    assert "cross-file duplication" in result["reason"].lower()
+                    assert isinstance(result, dict)
+                    assert result.get("decision") == "block"
+                    reason = result.get("reason", "")
+                    assert isinstance(reason, str)
+                    assert "cross-file duplication" in reason.lower()
 
     def test_naming_convention_violations(self, non_pep8_code):
         """Test naming convention verification."""
@@ -150,9 +162,13 @@ class TestPostToolUseHook:
         with patch("pathlib.Path.exists", return_value=True):
             with patch("pathlib.Path.read_text", return_value=non_pep8_code):
                 result = posttooluse_hook(hook_data, config)
-                assert result["decision"] == "block"
-                assert "non-pep8 function names" in result["reason"].lower()
-                assert "non-pep8 class names" in result["reason"].lower()
+                assert isinstance(result, dict)
+                assert result.get("decision") == "block"
+                reason = result.get("reason", "")
+                assert isinstance(reason, str)
+                reason_lower = reason.lower()
+                assert "non-pep8 function names" in reason_lower
+                assert "non-pep8 class names" in reason_lower
 
     def test_show_success_message(self, clean_code):
         """Test success message when enabled."""
@@ -165,11 +181,11 @@ class TestPostToolUseHook:
         with patch("pathlib.Path.exists", return_value=True):
             with patch("pathlib.Path.read_text", return_value=clean_code):
                 result = posttooluse_hook(hook_data, config)
-                assert result["decision"] == "approve"
-                assert (
-                    "passed post-write verification"
-                    in result["systemMessage"].lower()
-                )
+                assert isinstance(result, dict)
+                assert result.get("decision") == "approve"
+                system_msg = result.get("systemMessage", "")
+                assert isinstance(system_msg, str)
+                assert "passed post-write verification" in system_msg.lower()
 
     def test_no_message_when_success_disabled(self, clean_code):
         """Test no message when show_success is disabled."""
@@ -212,8 +228,11 @@ class TestPostToolUseHook:
                             mock_naming.return_value = ["⚠️ Issue 3"]
 
                             result = posttooluse_hook(hook_data, config)
-                            assert result["decision"] == "block"
-                            reason_text = result["reason"].lower()
+                            assert isinstance(result, dict)
+                            assert result.get("decision") == "block"
+                            reason = result.get("reason", "")
+                            assert isinstance(reason, str)
+                            reason_text = reason.lower()
                             assert "issue 1" in reason_text
                             assert "issue 2" in reason_text
                             assert "issue 3" in reason_text

tests/hooks/test_pretooluse.py

@@ -9,6 +9,13 @@ TEST_QUALITY_CONDITIONAL = (
 )
 
 
+def get_reason_str(result: dict[str, object]) -> str:
+    """Extract and assert reason field as string."""
+    reason = result["reason"]
+    assert isinstance(reason, str), f"Expected str, got {type(reason)}"
+    return reason
+
+
 class TestPreToolUseHook:
     """Test PreToolUse hook behavior."""
 
@@ -102,7 +109,9 @@ class TestPreToolUseHook:
 
             result = pretooluse_hook(hook_data, config)
             assert result["permissionDecision"] == "deny"
-            assert "quality check failed" in result["reason"].lower()
+            reason = result["reason"]
+            assert isinstance(reason, str)
+            assert "quality check failed" in reason.lower()
 
     def test_complex_code_ask_warn_mode(self, complex_code):
         """Test that complex code triggers ask in warn mode."""
@@ -147,7 +156,8 @@ class TestPreToolUseHook:
 
             result = pretooluse_hook(hook_data, config)
             assert result["permissionDecision"] == "allow"
-            assert "warning" in result.get("reason", "").lower()
+            reason = str(result.get("reason", ""))
+            assert "warning" in reason.lower()
 
     def test_duplicate_code_detection(self, duplicate_code):
         """Test internal duplicate detection."""
@@ -181,7 +191,7 @@ class TestPreToolUseHook:
 
                 result = pretooluse_hook(hook_data, config)
                 assert result["permissionDecision"] == "deny"
-                assert "duplication" in result["reason"].lower()
+                assert "duplicate" in get_reason_str(result).lower()
 
     def test_edit_tool_handling(self):
         """Test Edit tool content extraction."""
@@ -256,7 +266,7 @@ class TestPreToolUseHook:
         mock_check.assert_called_once()
         analyzed_content = mock_check.call_args[0][1]
         assert "def kept()" in analyzed_content
-        assert "typing.any" in result["reason"].lower()
+        assert "typing.any" in get_reason_str(result).lower()
 
     def test_state_tracking_enabled(self):
         """Test state tracking when enabled."""
@@ -294,7 +304,8 @@ class TestPreToolUseHook:
             result = pretooluse_hook(hook_data, config)
 
             assert result["permissionDecision"] == "allow"
-            assert "error" in result.get("reason", "").lower()
+            reason = str(result.get("reason", ""))
+            assert "error" in reason.lower()
 
     def test_custom_skip_patterns(self):
         """Test custom skip patterns."""
@@ -341,7 +352,7 @@ class TestPreToolUseHook:
 
             result = pretooluse_hook(hook_data, config)
             assert result["permissionDecision"] == "deny"
-            assert "modernization" in result["reason"].lower()
+            assert "modernization" in get_reason_str(result).lower()
 
     def test_type_hint_threshold(self):
         """Test type hint issue threshold."""
@@ -369,7 +380,7 @@ class TestPreToolUseHook:
 
             result = pretooluse_hook(hook_data, config)
             assert result["permissionDecision"] == "deny"
-            assert "type hints" in result["reason"].lower()
+            assert "type hints" in get_reason_str(result).lower()
 
     def test_any_usage_denied_on_analysis_failure(self):
         """Deny when typing.Any is detected even if analysis raises errors."""
@@ -392,8 +403,8 @@ class TestPreToolUseHook:
             result = pretooluse_hook(hook_data, config)
 
         assert result["permissionDecision"] == "deny"
-        assert "typing.any" in result["reason"].lower()
-        assert "fix these issues" in result["reason"].lower()
+        assert "typing.any" in get_reason_str(result).lower()
+        assert "fix these issues" in get_reason_str(result).lower()
 
     def test_any_usage_denied(self):
         """Test that typing.Any usage triggers a denial."""
@@ -412,7 +423,7 @@ class TestPreToolUseHook:
 
             result = pretooluse_hook(hook_data, config)
             assert result["permissionDecision"] == "deny"
-            assert "any" in result["reason"].lower()
+            assert "any" in get_reason_str(result).lower()
 
     def test_any_usage_detected_in_multiedit(self):
         """Test that MultiEdit content is scanned for typing.Any usage."""
@@ -442,7 +453,7 @@ class TestPreToolUseHook:
 
             result = pretooluse_hook(hook_data, config)
             assert result["permissionDecision"] == "deny"
-            assert "any" in result["reason"].lower()
+            assert "any" in get_reason_str(result).lower()
 
     def test_type_ignore_usage_denied_on_analysis_failure(self):
         config = QualityConfig()
@@ -464,8 +475,8 @@ class TestPreToolUseHook:
             result = pretooluse_hook(hook_data, config)
 
         assert result["permissionDecision"] == "deny"
-        assert "type: ignore" in result["reason"].lower()
-        assert "fix these issues" in result["reason"].lower()
+        assert "type: ignore" in get_reason_str(result).lower()
+        assert "fix these issues" in get_reason_str(result).lower()
 
     def test_type_ignore_usage_denied(self):
         config = QualityConfig(enforcement_mode="strict")
@@ -484,7 +495,7 @@ class TestPreToolUseHook:
 
             result = pretooluse_hook(hook_data, config)
             assert result["permissionDecision"] == "deny"
-            assert "type: ignore" in result["reason"].lower()
+            assert "type: ignore" in get_reason_str(result).lower()
 
     def test_type_ignore_usage_detected_in_multiedit(self):
         config = QualityConfig()
@@ -515,7 +526,7 @@ class TestPreToolUseHook:
 
             result = pretooluse_hook(hook_data, config)
             assert result["permissionDecision"] == "deny"
-            assert "type: ignore" in result["reason"].lower()
+            assert "type: ignore" in get_reason_str(result).lower()
 
 
 class TestTestQualityChecks:
@@ -558,7 +569,7 @@ class TestTestQualityChecks:
 
                 # Should be denied due to test quality issues
                 assert result["permissionDecision"] == "deny"
-                assert "test quality" in result["reason"].lower()
+                assert "test quality" in get_reason_str(result).lower()
                 mock_test_check.assert_called_once()
 
     def test_test_quality_checks_disabled_for_non_test_files(self):
@@ -652,7 +663,7 @@ class TestTestQualityChecks:
 
                 # Should be denied due to test quality issues
                 assert result["permissionDecision"] == "deny"
-                assert "test quality" in result["reason"].lower()
+                assert "test quality" in get_reason_str(result).lower()
                 mock_test_check.assert_called_once()
 
     def test_test_quality_checks_with_multiedit_tool(self):
@@ -692,7 +703,7 @@ class TestTestQualityChecks:
 
                 # Should be denied due to test quality issues
                 assert result["permissionDecision"] == "deny"
-                assert "test quality" in result["reason"].lower()
+                assert "test quality" in get_reason_str(result).lower()
                 mock_test_check.assert_called_once()
 
     def test_test_quality_checks_combined_with_other_prechecks(self):
@@ -721,7 +732,7 @@ class TestTestQualityChecks:
 
                 # Should be denied due to multiple precheck issues
                 assert result["permissionDecision"] == "deny"
-                assert "any" in result["reason"].lower()
-                assert "type: ignore" in result["reason"].lower()
-                assert "test quality" in result["reason"].lower()
+                assert "any" in get_reason_str(result).lower()
+                assert "type: ignore" in get_reason_str(result).lower()
+                assert "test quality" in get_reason_str(result).lower()
                 mock_test_check.assert_called_once()

typings/pytest/__init__.pyi

@@ -0,0 +1,37 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from _pytest import __version__, version_tuple
+from _pytest._code import ExceptionInfo
+from _pytest.assertion import register_assert_rewrite
+from _pytest.cacheprovider import Cache
+from _pytest.capture import CaptureFixture
+from _pytest.config import Config, ExitCode, PytestPluginManager, UsageError, cmdline, console_main, hookimpl, hookspec, main
+from _pytest.config.argparsing import OptionGroup, Parser
+from _pytest.debugging import pytestPDB as __pytestPDB
+from _pytest.doctest import DoctestItem
+from _pytest.fixtures import FixtureDef, FixtureLookupError, FixtureRequest, fixture, yield_fixture
+from _pytest.freeze_support import freeze_includes
+from _pytest.legacypath import TempdirFactory, Testdir
+from _pytest.logging import LogCaptureFixture
+from _pytest.main import Dir, Session
+from _pytest.mark import HIDDEN_PARAM, MARK_GEN as mark, Mark, MarkDecorator, MarkGenerator, param
+from _pytest.monkeypatch import MonkeyPatch
+from _pytest.nodes import Collector, Directory, File, Item
+from _pytest.outcomes import exit, fail, importorskip, skip, xfail
+from _pytest.pytester import HookRecorder, LineMatcher, Pytester, RecordedHookCall, RunResult
+from _pytest.python import Class, Function, Metafunc, Module, Package
+from _pytest.python_api import approx
+from _pytest.raises import RaisesExc, RaisesGroup, raises
+from _pytest.recwarn import WarningsRecorder, deprecated_call, warns
+from _pytest.reports import CollectReport, TestReport
+from _pytest.runner import CallInfo
+from _pytest.stash import Stash, StashKey
+from _pytest.terminal import TerminalReporter, TestShortLogReport
+from _pytest.tmpdir import TempPathFactory
+from _pytest.warning_types import PytestAssertRewriteWarning, PytestCacheWarning, PytestCollectionWarning, PytestConfigWarning, PytestDeprecationWarning, PytestExperimentalApiWarning, PytestFDWarning, PytestRemovedIn9Warning, PytestReturnNotNoneWarning, PytestUnhandledThreadExceptionWarning, PytestUnknownMarkWarning, PytestUnraisableExceptionWarning, PytestWarning
+
+"""pytest: unit and functional testing with Python."""
+set_trace = ...
+__all__ = ["HIDDEN_PARAM", "Cache", "CallInfo", "CaptureFixture", "Class", "CollectReport", "Collector", "Config", "Dir", "Directory", "DoctestItem", "ExceptionInfo", "ExitCode", "File", "FixtureDef", "FixtureLookupError", "FixtureRequest", "Function", "HookRecorder", "Item", "LineMatcher", "LogCaptureFixture", "Mark", "MarkDecorator", "MarkGenerator", "Metafunc", "Module", "MonkeyPatch", "OptionGroup", "Package", "Parser", "PytestAssertRewriteWarning", "PytestCacheWarning", "PytestCollectionWarning", "PytestConfigWarning", "PytestDeprecationWarning", "PytestExperimentalApiWarning", "PytestFDWarning", "PytestPluginManager", "PytestRemovedIn9Warning", "PytestReturnNotNoneWarning", "PytestUnhandledThreadExceptionWarning", "PytestUnknownMarkWarning", "PytestUnraisableExceptionWarning", "PytestWarning", "Pytester", "RaisesExc", "RaisesGroup", "RecordedHookCall", "RunResult", "Session", "Stash", "StashKey", "TempPathFactory", "TempdirFactory", "TerminalReporter", "TestReport", "TestShortLogReport", "Testdir", "UsageError", "WarningsRecorder", "__version__", "approx", "cmdline", "console_main", "deprecated_call", "exit", "fail", "fixture", "freeze_includes", "hookimpl", "hookspec", "importorskip", "main", "mark", "param", "raises", "register_assert_rewrite", "set_trace", "skip", "version_tuple", "warns", "xfail", "yield_fixture"]

typings/pytest/__main__.pyi

@@ -0,0 +1,7 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+"""The pytest entry point."""
+if __name__ == "__main__":
+    ...

typings/radon/__init__.pyi

@@ -0,0 +1,13 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+'''This module contains the main() function, which is the entry point for the
+command line interface.'''
+__version__ = ...
+def main(): # -> None:
+    '''The entry point for Setuptools.'''
+    ...
+
+if __name__ == '__main__':
+    ...

typings/radon/__main__.pyi

@@ -0,0 +1,5 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+"""Module allowing for ``python -m radon ...``."""

typings/radon/cli/__init__.pyi

@@ -0,0 +1,229 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+import inspect
+import os
+import sys
+import tomllib
+import radon.complexity as cc_mod
+import configparser
+from contextlib import contextmanager
+from mando import Program
+from radon.cli.colors import BRIGHT, RED, RESET
+from radon.cli.harvest import CCHarvester, HCHarvester, MIHarvester, RawHarvester
+
+'''In this module the CLI interface is created.'''
+TOMLLIB_PRESENT = ...
+if sys.version_info[0] == 2:
+    ...
+else:
+    ...
+CONFIG_SECTION_NAME = ...
+class FileConfig:
+    '''
+    Yield default options by reading local configuration files.
+    '''
+    def __init__(self) -> None:
+        ...
+    
+    def get_value(self, key, type, default): # -> int | bool | str:
+        ...
+    
+    @staticmethod
+    def toml_config(): # -> dict[Any, Any] | Any:
+        ...
+    
+    @staticmethod
+    def file_config(): # -> ConfigParser:
+        '''Return any file configuration discovered'''
+        ...
+    
+
+
+_cfg = ...
+program = ...
+@program.command
+@program.arg('paths', nargs='+')
+def cc(paths, min=..., max=..., show_complexity=..., average=..., exclude=..., ignore=..., order=..., json=..., no_assert=..., show_closures=..., total_average=..., xml=..., md=..., codeclimate=..., output_file=..., include_ipynb=..., ipynb_cells=...): # -> None:
+    '''Analyze the given Python modules and compute Cyclomatic
+    Complexity (CC).
+
+    The output can be filtered using the *min* and *max* flags. In addition
+    to that, by default complexity score is not displayed.
+
+    :param paths: The paths where to find modules or packages to analyze. More
+        than one path is allowed.
+    :param -n, --min <str>: The minimum complexity to display (default to A).
+    :param -x, --max <str>: The maximum complexity to display (default to F).
+    :param -e, --exclude <str>: Exclude files only when their path matches one
+        of these glob patterns. Usually needs quoting at the command line.
+    :param -i, --ignore <str>: Ignore directories when their name matches one
+        of these glob patterns: radon won't even descend into them. By default,
+        hidden directories (starting with '.') are ignored.
+    :param -s, --show-complexity: Whether or not to show the actual complexity
+        score together with the A-F rank. Default to False.
+    :param -a, --average: If True, at the end of the analysis display the
+        average complexity. Default to False.
+    :param --total-average: Like `-a, --average`, but it is not influenced by
+        `min` and `max`. Every analyzed block is counted, no matter whether it
+        is displayed or not.
+    :param -o, --order <str>: The ordering function. Can be SCORE, LINES or
+        ALPHA.
+    :param -j, --json: Format results in JSON.
+    :param --xml: Format results in XML (compatible with CCM).
+    :param --md: Format results in Markdown.
+    :param --codeclimate: Format results for Code Climate.
+    :param --no-assert: Do not count `assert` statements when computing
+        complexity.
+    :param --show-closures: Add closures/inner classes to the output.
+    :param -O, --output-file <str>: The output file (default to stdout).
+    :param --include-ipynb: Include IPython Notebook files
+    :param --ipynb-cells: Include reports for individual IPYNB cells
+    '''
+    ...
+
+@program.command
+@program.arg('paths', nargs='+')
+def raw(paths, exclude=..., ignore=..., summary=..., json=..., output_file=..., include_ipynb=..., ipynb_cells=...): # -> None:
+    '''Analyze the given Python modules and compute raw metrics.
+
+    :param paths: The paths where to find modules or packages to analyze. More
+        than one path is allowed.
+    :param -e, --exclude <str>: Exclude files only when their path matches one
+        of these glob patterns. Usually needs quoting at the command line.
+    :param -i, --ignore <str>: Ignore directories when their name matches one
+        of these glob patterns: radon won't even descend into them. By default,
+        hidden directories (starting with '.') are ignored.
+    :param -s, --summary:  If given, at the end of the analysis display the
+        summary of the gathered metrics. Default to False.
+    :param -j, --json: Format results in JSON. Note that the JSON export does
+        not include the summary (enabled with `-s, --summary`).
+    :param -O, --output-file <str>: The output file (default to stdout).
+    :param --include-ipynb: Include IPython Notebook files
+    :param --ipynb-cells: Include reports for individual IPYNB cells
+    '''
+    ...
+
+@program.command
+@program.arg('paths', nargs='+')
+def mi(paths, min=..., max=..., multi=..., exclude=..., ignore=..., show=..., json=..., sort=..., output_file=..., include_ipynb=..., ipynb_cells=...): # -> None:
+    '''Analyze the given Python modules and compute the Maintainability Index.
+
+    The maintainability index (MI) is a compound metric, with the primary aim
+    being to determine how easy it will be to maintain a particular body of
+    code.
+
+    :param paths: The paths where to find modules or packages to analyze. More
+        than one path is allowed.
+    :param -n, --min <str>: The minimum MI to display (default to A).
+    :param -x, --max <str>: The maximum MI to display (default to C).
+    :param -e, --exclude <str>: Exclude files only when their path matches one
+        of these glob patterns. Usually needs quoting at the command line.
+    :param -i, --ignore <str>: Ignore directories when their name matches one
+        of these glob patterns: radon won't even descend into them. By default,
+        hidden directories (starting with '.') are ignored.
+    :param -m, --multi: If given, multiline strings are not counted as
+        comments.
+    :param -s, --show: If given, the actual MI value is shown in results.
+    :param -j, --json: Format results in JSON.
+    :param --sort: If given, results are sorted in ascending order.
+    :param -O, --output-file <str>: The output file (default to stdout).
+    :param --include-ipynb: Include IPython Notebook files
+    :param --ipynb-cells: Include reports for individual IPYNB cells
+    '''
+    ...
+
+@program.command
+@program.arg("paths", nargs="+")
+def hal(paths, exclude=..., ignore=..., json=..., functions=..., output_file=..., include_ipynb=..., ipynb_cells=...): # -> None:
+    """
+    Analyze the given Python modules and compute their Halstead metrics.
+
+    The Halstead metrics are a series of measurements meant to quantitatively
+    measure the complexity of code, including the difficulty a programmer would
+    have in writing it.
+
+    :param paths: The paths where to find modules or packages to analyze. More
+        than one path is allowed.
+    :param -e, --exclude <str>: Exclude files only when their path matches one
+        of these glob patterns. Usually needs quoting at the command line.
+    :param -i, --ignore <str>: Ignore directories when their name matches one
+        of these glob patterns: radon won't even descend into them. By default,
+        hidden directories (starting with '.') are ignored.
+    :param -j, --json: Format results in JSON.
+    :param -f, --functions: Analyze files by top-level functions instead of as
+        a whole.
+    :param -O, --output-file <str>: The output file (default to stdout).
+    :param --include-ipynb: Include IPython Notebook files
+    :param --ipynb-cells: Include reports for individual IPYNB cells
+    """
+    ...
+
+class Config:
+    '''An object holding config values.'''
+    def __init__(self, **kwargs) -> None:
+        '''Configuration values are passed as keyword parameters.'''
+        ...
+    
+    def __getattr__(self, attr): # -> Any:
+        '''If an attribute is not found inside the config values, the request
+        is handed to `__getattribute__`.
+        '''
+        ...
+    
+    def __repr__(self): # -> str:
+        '''The string representation of the Config object is just the one of
+        the dictionary holding the configuration values.
+        '''
+        ...
+    
+    def __eq__(self, other) -> bool:
+        '''Two Config objects are equals if their contents are equal.'''
+        ...
+    
+    @classmethod
+    def from_function(cls, func): # -> Self:
+        '''Construct a Config object from a function's defaults.'''
+        ...
+    
+
+
+def log_result(harvester, **kwargs): # -> None:
+    '''Log the results of an :class:`~radon.cli.harvest.Harvester object.
+
+    Keywords parameters determine how the results are formatted. If *json* is
+    `True`, then `harvester.as_json()` is called. If *xml* is `True`, then
+    `harvester.as_xml()` is called. If *codeclimate* is True, then
+    `harvester.as_codeclimate_issues()` is called.
+    Otherwise, `harvester.to_terminal()` is executed and `kwargs` is directly
+    passed to the :func:`~radon.cli.log` function.
+    '''
+    ...
+
+def log(msg, *args, **kwargs): # -> None:
+    '''Log a message, passing *args* to the strings' `format()` method.
+
+    *indent*, if present as a keyword argument, specifies the indent level, so
+    that `indent=0` will log normally, `indent=1` will indent the message by 4
+    spaces, &c..
+    *noformat*, if present and True, will cause the message not to be formatted
+    in any way.
+    '''
+    ...
+
+def log_list(lst, *args, **kwargs): # -> None:
+    '''Log an entire list, line by line. All the arguments are directly passed
+    to :func:`~radon.cli.log`.
+    '''
+    ...
+
+def log_error(msg, *args, **kwargs): # -> None:
+    '''Log an error message. Arguments are the same as log().'''
+    ...
+
+@contextmanager
+def outstream(outfile=...): # -> Generator[TextIOWrapper[_WrappedBuffer] | TextIO | Any, Any, None]:
+    '''Encapsulate output stream creation as a context manager'''
+    ...
+

typings/radon/cli/colors.pyi

@@ -0,0 +1,14 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+'''Module holding constants used to format lines that are printed to the
+terminal.
+'''
+def color_enabled(): # -> bool:
+    ...
+
+RANKS_COLORS = ...
+LETTERS_COLORS = ...
+MI_RANKS = ...
+TEMPLATE = ...

typings/radon/cli/harvest.pyi

@@ -0,0 +1,189 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+import sys
+
+'''This module holds the base Harvester class and all its subclassess.'''
+if sys.version_info[0] < 3:
+    ...
+else:
+    ...
+SUPPORTS_IPYNB = ...
+class Harvester:
+    '''Base class defining the interface of a Harvester object.
+
+    A Harvester has the following lifecycle:
+
+    1. **Initialization**: `h = Harvester(paths, config)`
+
+    2. **Execution**: `r = h.results`. `results` holds an iterable object.
+       The first time `results` is accessed, `h.run()` is called. This method
+       should not be subclassed. Instead, the :meth:`gobble` method should be
+       implemented.
+
+    3. **Reporting**: the methods *as_json* and *as_xml* return a string
+       with the corrisponding format. The method *to_terminal* is a generator
+       that yields the lines to be printed in the terminal.
+
+    This class is meant to be subclasses and cannot be used directly, since
+    the methods :meth:`gobble`, :meth:`as_xml` and :meth:`to_terminal` are
+    not implemented.
+    '''
+    def __init__(self, paths, config) -> None:
+        '''Initialize the Harvester.
+
+        *paths* is a list of paths to analyze.
+        *config* is a :class:`~radon.cli.Config` object holding the
+        configuration values specific to the Harvester.
+        '''
+        ...
+    
+    def gobble(self, fobj):
+        '''Subclasses must implement this method to define behavior.
+
+        This method is called for every file to analyze. *fobj* is the file
+        object. This method should return the results from the analysis,
+        preferably a dictionary.
+        '''
+        ...
+    
+    def run(self): # -> Generator[tuple[Any | Literal['-'], Any] | tuple[str, Any] | tuple[Any | Literal['-'], dict[str, str]], Any, None]:
+        '''Start the analysis. For every file, this method calls the
+        :meth:`gobble` method. Results are yielded as tuple:
+        ``(filename, analysis_results)``.
+        '''
+        ...
+    
+    @property
+    def results(self): # -> list[Any] | Generator[tuple[Any | Literal['-'], Any] | tuple[str, Any] | tuple[Any | Literal['-'], dict[str, str]], Any, None]:
+        '''This property holds the results of the analysis.
+
+        The first time it is accessed, an iterator is returned. Its
+        elements are cached into a list as it is iterated over. Therefore, if
+        `results` is accessed multiple times after the first one, a list will
+        be returned.
+        '''
+        ...
+    
+    def as_json(self): # -> str:
+        '''Format the results as JSON.'''
+        ...
+    
+    def as_xml(self):
+        '''Format the results as XML.'''
+        ...
+    
+    def as_md(self):
+        '''Format the results as Markdown.'''
+        ...
+    
+    def as_codeclimate_issues(self):
+        '''Format the results as Code Climate issues.'''
+        ...
+    
+    def to_terminal(self):
+        '''Yields tuples representing lines to be printed to a terminal.
+
+        The tuples have the following format: ``(line, args, kwargs)``.
+        The line is then formatted with `line.format(*args, **kwargs)`.
+        '''
+        ...
+    
+
+
+class CCHarvester(Harvester):
+    '''A class that analyzes Python modules' Cyclomatic Complexity.'''
+    def gobble(self, fobj): # -> list[Any]:
+        '''Analyze the content of the file object.'''
+        ...
+    
+    def as_json(self): # -> str:
+        '''Format the results as JSON.'''
+        ...
+    
+    def as_xml(self): # -> str:
+        '''Format the results as XML. This is meant to be compatible with
+        Jenkin's CCM plugin. Therefore not all the fields are kept.
+        '''
+        ...
+    
+    def as_md(self): # -> str:
+        '''Format the results as Markdown.'''
+        ...
+    
+    def as_codeclimate_issues(self): # -> list[Any]:
+        '''Format the result as Code Climate issues.'''
+        ...
+    
+    def to_terminal(self): # -> Generator[tuple[Any | str, tuple[Any | str], dict[str, bool]] | tuple[Any | str, tuple[()], dict[Any, Any]] | tuple[list[Any], tuple[()], dict[str, int]] | tuple[LiteralString, tuple[int], dict[Any, Any]] | tuple[Literal['Average complexity: {0}{1} ({2}){3}'], tuple[str, str, float | Any, str], dict[Any, Any]], Any, None]:
+        '''Yield lines to be printed in a terminal.'''
+        ...
+    
+
+
+class RawHarvester(Harvester):
+    '''A class that analyzes Python modules' raw metrics.'''
+    headers = ...
+    def gobble(self, fobj): # -> dict[Any, Any]:
+        '''Analyze the content of the file object.'''
+        ...
+    
+    def as_xml(self):
+        '''Placeholder method. Currently not implemented.'''
+        ...
+    
+    def to_terminal(self): # -> Generator[tuple[Any | str, tuple[Any | str], dict[str, bool]] | tuple[Any | str, tuple[()], dict[Any, Any]] | tuple[Literal['{0}: {1}'], tuple[str, Any | str], dict[str, int]] | tuple[Literal['- Comment Stats'], tuple[()], dict[str, int]] | tuple[Literal['(C % L): {0:.0%}'], tuple[Any], dict[str, int]] | tuple[Literal['(C % S): {0:.0%}'], tuple[Any], dict[str, int]] | tuple[Literal['(C + M % L): {0:.0%}'], tuple[Any], dict[str, int]] | tuple[Literal['** Total **'], tuple[()], dict[Any, Any]] | tuple[Literal['{0}: {1}'], tuple[str, int], dict[str, int]] | tuple[Literal['(C % L): {0:.0%}'], tuple[float], dict[str, int]] | tuple[Literal['(C % S): {0:.0%}'], tuple[float], dict[str, int]] | tuple[Literal['(C + M % L): {0:.0%}'], tuple[float], dict[str, int]], Any, None]:
+        '''Yield lines to be printed to a terminal.'''
+        ...
+    
+
+
+class MIHarvester(Harvester):
+    '''A class that analyzes Python modules' Maintainability Index.'''
+    def gobble(self, fobj): # -> dict[str, float | str]:
+        '''Analyze the content of the file object.'''
+        ...
+    
+    @property
+    def filtered_results(self): # -> Generator[tuple[Any | str, Any | dict[str, str]], Any, None]:
+        '''Filter results with respect with their rank.'''
+        ...
+    
+    def as_json(self): # -> str:
+        '''Format the results as JSON.'''
+        ...
+    
+    def as_xml(self):
+        '''Placeholder method. Currently not implemented.'''
+        ...
+    
+    def to_terminal(self): # -> Generator[tuple[Any, tuple[Any], dict[str, bool]] | tuple[Literal['{0} - {1}{2}{3}{4}'], tuple[Any, str, Any, str, str], dict[Any, Any]], Any, None]:
+        '''Yield lines to be printed to a terminal.'''
+        ...
+    
+
+
+class HCHarvester(Harvester):
+    """Computes the Halstead Complexity of Python modules."""
+    def __init__(self, paths, config) -> None:
+        ...
+    
+    def gobble(self, fobj): # -> Halstead:
+        """Analyze the content of the file object."""
+        ...
+    
+    def as_json(self): # -> str:
+        """Format the results as JSON."""
+        ...
+    
+    def to_terminal(self): # -> Generator[tuple[str, tuple[()], dict[Any, Any]] | tuple[str, tuple[()], dict[str, int]], Any, None]:
+        """Yield lines to be printed to the terminal."""
+        ...
+    
+
+
+def hal_report_to_terminal(report, base_indent=...): # -> Generator[tuple[str, tuple[()], dict[str, int]], Any, None]:
+    """Yield lines from the HalsteadReport to print to the terminal."""
+    ...
+

typings/radon/cli/tools.pyi

@@ -0,0 +1,99 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+import platform
+
+'''This module contains various utility functions used in the CLI interface.
+Attributes:
+    _encoding (str): encoding with all files will be opened. Configured by
+    environment variable RADONFILESENCODING
+'''
+SUPPORTS_IPYNB = ...
+if platform.python_implementation() == 'PyPy':
+    ...
+else:
+    _encoding = ...
+def iter_filenames(paths, exclude=..., ignore=...): # -> Generator[Any | Literal['-'], Any, None]:
+    '''A generator that yields all sub-paths of the ones specified in
+    `paths`. Optional `exclude` filters can be passed as a comma-separated
+    string of regexes, while `ignore` filters are a comma-separated list of
+    directory names to ignore. Ignore patterns are can be plain names or glob
+    patterns. If paths contains only a single hyphen, stdin is implied,
+    returned as is.
+    '''
+    ...
+
+def explore_directories(start, exclude, ignore): # -> Generator[Any, Any, None]:
+    '''Explore files and directories under `start`. `explore` and `ignore`
+    arguments are the same as in :func:`iter_filenames`.
+    '''
+    ...
+
+def filter_out(strings, patterns): # -> Generator[Any, Any, None]:
+    '''Filter out any string that matches any of the specified patterns.'''
+    ...
+
+def cc_to_dict(obj): # -> dict[str, str]:
+    '''Convert an object holding CC results into a dictionary. This is meant
+    for JSON dumping.'''
+    ...
+
+def raw_to_dict(obj): # -> dict[Any, Any]:
+    '''Convert an object holding raw analysis results into a dictionary. This
+    is meant for JSON dumping.'''
+    ...
+
+def dict_to_xml(results): # -> str:
+    '''Convert a dictionary holding CC analysis result into a string containing
+    xml.'''
+    ...
+
+def dict_to_md(results): # -> str:
+    ...
+
+def dict_to_codeclimate_issues(results, threshold=...): # -> list[Any]:
+    '''Convert a dictionary holding CC analysis results into Code Climate
+     issue json.'''
+    ...
+
+def cc_to_terminal(results, show_complexity, min, max, total_average): # -> tuple[list[Any], float | Any, int]:
+    '''Transfom Cyclomatic Complexity results into a 3-elements tuple:
+
+        ``(res, total_cc, counted)``
+
+    `res` is a list holding strings that are specifically formatted to be
+    printed to a terminal.
+    `total_cc` is a number representing the total analyzed cyclomatic
+    complexity.
+    `counted` holds the number of the analyzed blocks.
+
+    If *show_complexity* is `True`, then the complexity of a block will be
+    shown in the terminal line alongside its rank.
+    *min* and *max* are used to control which blocks are shown in the resulting
+    list. A block is formatted only if its rank is `min <= rank <= max`.
+    If *total_average* is `True`, the `total_cc` and `counted` count every
+    block, regardless of the fact that they are formatted in `res` or not.
+    '''
+    ...
+
+def format_cc_issue(path, description, content, category, beginline, endline, remediation_points, fingerprint): # -> str:
+    '''Return properly formatted Code Climate issue json.'''
+    ...
+
+def get_remediation_points(complexity, grade_threshold): # -> Literal[0]:
+    '''Calculate quantity of remediation work needed to reduce complexity to grade
+    threshold permitted.'''
+    ...
+
+def get_content(): # -> str:
+    '''Return explanation string for Code Climate issue document.'''
+    ...
+
+def get_fingerprint(path, additional_parts): # -> str:
+    '''Return fingerprint string for Code Climate issue document.'''
+    ...
+
+def strip_ipython(code): # -> LiteralString:
+    ...
+

typings/radon/complexity.pyi

@@ -0,0 +1,81 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+'''This module contains all high-level helpers function that allow to work with
+Cyclomatic Complexity
+'''
+SCORE = ...
+LINES = ...
+ALPHA = ...
+def cc_rank(cc): # -> str:
+    r'''Rank the complexity score from A to F, where A stands for the simplest
+    and best score and F the most complex and worst one:
+
+    ============= =====================================================
+        1 - 5        A (low risk - simple block)
+        6 - 10       B (low risk - well structured and stable block)
+        11 - 20      C (moderate risk - slightly complex block)
+        21 - 30      D (more than moderate risk - more complex block)
+        31 - 40      E (high risk - complex block, alarming)
+        41+          F (very high risk - error-prone, unstable block)
+    ============= =====================================================
+
+    Here *block* is used in place of function, method or class.
+
+    The formula used to convert the score into an index is the following:
+
+    .. math::
+
+        \text{rank} = \left \lceil \dfrac{\text{score}}{10} \right \rceil
+        - H(5 - \text{score})
+
+    where ``H(s)`` stands for the Heaviside Step Function.
+    The rank is then associated to a letter (0 = A, 5 = F).
+    '''
+    ...
+
+def average_complexity(blocks): # -> Any | float | Literal[0]:
+    '''Compute the average Cyclomatic complexity from the given blocks.
+    Blocks must be either :class:`~radon.visitors.Function` or
+    :class:`~radon.visitors.Class`. If the block list is empty, then 0 is
+    returned.
+    '''
+    ...
+
+def sorted_results(blocks, order=...): # -> list[Any]:
+    '''Given a ComplexityVisitor instance, returns a list of sorted blocks
+    with respect to complexity. A block is a either
+    :class:`~radon.visitors.Function` object or a
+    :class:`~radon.visitors.Class` object.
+    The blocks are sorted in descending order from the block with the highest
+    complexity.
+
+    The optional `order` parameter indicates how to sort the blocks. It can be:
+
+        * `LINES`: sort by line numbering;
+        * `ALPHA`: sort by name (from A to Z);
+        * `SCORE`: sorty by score (descending).
+
+    Default is `SCORE`.
+    '''
+    ...
+
+def add_inner_blocks(blocks): # -> list[Any]:
+    '''Process a list of blocks by adding all closures and inner classes as
+    top-level blocks.
+    '''
+    ...
+
+def cc_visit(code, **kwargs): # -> list[Any]:
+    '''Visit the given code with :class:`~radon.visitors.ComplexityVisitor`.
+    All the keyword arguments are directly passed to the visitor.
+    '''
+    ...
+
+def cc_visit_ast(ast_node, **kwargs): # -> list[Any]:
+    '''Visit the AST node with :class:`~radon.visitors.ComplexityVisitor`. All
+    the keyword arguments are directly passed to the visitor.
+    '''
+    ...
+

typings/radon/contrib/__init__.pyi

@@ -0,0 +1,4 @@
+"""
+This type stub file was generated by pyright.
+"""
+

typings/radon/metrics.pyi

@@ -0,0 +1,84 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+'''Module holding functions related to miscellaneous metrics, such as Halstead
+metrics or the Maintainability Index.
+'''
+HalsteadReport = ...
+Halstead = ...
+def h_visit(code): # -> Halstead:
+    '''Compile the code into an AST tree and then pass it to
+    :func:`~radon.metrics.h_visit_ast`.
+    '''
+    ...
+
+def h_visit_ast(ast_node): # -> Halstead:
+    '''
+    Visit the AST node using the :class:`~radon.visitors.HalsteadVisitor`
+    visitor. The results are `HalsteadReport` namedtuples with the following
+    fields:
+
+        * h1: the number of distinct operators
+        * h2: the number of distinct operands
+        * N1: the total number of operators
+        * N2: the total number of operands
+        * h: the vocabulary, i.e. h1 + h2
+        * N: the length, i.e. N1 + N2
+        * calculated_length: h1 * log2(h1) + h2 * log2(h2)
+        * volume: V = N * log2(h)
+        * difficulty: D = h1 / 2 * N2 / h2
+        * effort: E = D * V
+        * time: T = E / 18 seconds
+        * bugs: B = V / 3000 - an estimate of the errors in the implementation
+
+    The actual return of this function is a namedtuple with the following
+    fields:
+
+        * total: a `HalsteadReport` namedtuple for the entire scanned file
+        * functions: a list of `HalsteadReport`s for each toplevel function
+
+    Nested functions are not tracked.
+    '''
+    ...
+
+def halstead_visitor_report(visitor): # -> HalsteadReport:
+    """Return a HalsteadReport from a HalsteadVisitor instance."""
+    ...
+
+def mi_compute(halstead_volume, complexity, sloc, comments): # -> float:
+    '''Compute the Maintainability Index (MI) given the Halstead Volume, the
+    Cyclomatic Complexity, the SLOC number and the number of comment lines.
+    Usually it is not used directly but instead :func:`~radon.metrics.mi_visit`
+    is preferred.
+    '''
+    ...
+
+def mi_parameters(code, count_multi=...): # -> tuple[Any, int, Any, Any | Literal[0]]:
+    '''Given a source code snippet, compute the necessary parameters to
+    compute the Maintainability Index metric. These include:
+
+        * the Halstead Volume
+        * the Cyclomatic Complexity
+        * the number of LLOC (Logical Lines of Code)
+        * the percent of lines of comment
+
+    :param multi: If True, then count multiline strings as comment lines as
+        well. This is not always safe because Python multiline strings are not
+        always docstrings.
+    '''
+    ...
+
+def mi_visit(code, multi): # -> float:
+    '''Visit the code and compute the Maintainability Index (MI) from it.'''
+    ...
+
+def mi_rank(score): # -> str:
+    r'''Rank the score with a letter:
+
+        * A if :math:`\text{score} > 19`;
+        * B if :math:`9 < \text{score} \le 19`;
+        * C if :math:`\text{score} \le 9`.
+    '''
+    ...
+

typings/radon/raw.pyi

@@ -0,0 +1,43 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+'''This module contains functions related to raw metrics.
+
+The main function is :func:`~radon.raw.analyze`, and should be the only one
+that is used.
+'''
+__all__ = ['OP', 'COMMENT', 'TOKEN_NUMBER', 'NL', 'NEWLINE', 'EM', 'Module', '_generate', '_fewer_tokens', '_find', '_logical', 'analyze']
+COMMENT = ...
+OP = ...
+NL = ...
+NEWLINE = ...
+EM = ...
+TOKEN_NUMBER = ...
+Module = ...
+def is_single_token(token_number, tokens): # -> bool:
+    '''Is this a single token matching token_number followed by ENDMARKER, NL
+    or NEWLINE tokens.
+    '''
+    ...
+
+def analyze(source): # -> Module:
+    '''Analyze the source code and return a namedtuple with the following
+    fields:
+
+        * **loc**: The number of lines of code (total)
+        * **lloc**: The number of logical lines of code
+        * **sloc**: The number of source lines of code (not necessarily
+            corresponding to the LLOC)
+        * **comments**: The number of Python comment lines
+        * **multi**: The number of lines which represent multi-line strings
+        * **single_comments**: The number of lines which are just comments with
+            no code
+        * **blank**: The number of blank lines (or whitespace-only ones)
+
+    The equation :math:`sloc + blanks + multi + single_comments = loc` should
+    always hold.  Multiline strings are not counted as comments, since, to the
+    Python interpreter, they are not comments but strings.
+    '''
+    ...
+

typings/radon/tests/__init__.pyi

@@ -0,0 +1,4 @@
+"""
+This type stub file was generated by pyright.
+"""
+

typings/radon/visitors.pyi

@@ -0,0 +1,250 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+import ast
+
+'''This module contains the ComplexityVisitor class which is where all the
+analysis concerning Cyclomatic Complexity is done. There is also the class
+HalsteadVisitor, that counts Halstead metrics.'''
+GET_COMPLEXITY = ...
+GET_REAL_COMPLEXITY = ...
+NAMES_GETTER = ...
+GET_ENDLINE = ...
+BaseFunc = ...
+BaseClass = ...
+def code2ast(source): # -> Module:
+    '''Convert a string object into an AST object.
+
+    This function is retained for backwards compatibility, but it no longer
+    attemps any conversions. It's equivalent to a call to ``ast.parse``.
+    '''
+    ...
+
+class Function(BaseFunc):
+    '''Object represeting a function block.'''
+    @property
+    def letter(self): # -> Literal['M', 'F']:
+        '''The letter representing the function. It is `M` if the function is
+        actually a method, `F` otherwise.
+        '''
+        ...
+    
+    @property
+    def fullname(self): # -> str:
+        '''The full name of the function. If it is a method, then the full name
+        is:
+                {class name}.{method name}
+        Otherwise it is just the function name.
+        '''
+        ...
+    
+    def __str__(self) -> str:
+        '''String representation of a function block.'''
+        ...
+    
+
+
+class Class(BaseClass):
+    '''Object representing a class block.'''
+    letter = ...
+    @property
+    def fullname(self):
+        '''The full name of the class. It is just its name. This attribute
+        exists for consistency (see :data:`Function.fullname`).
+        '''
+        ...
+    
+    @property
+    def complexity(self): # -> int:
+        '''The average complexity of the class. It corresponds to the average
+        complexity of its methods plus one.
+        '''
+        ...
+    
+    def __str__(self) -> str:
+        '''String representation of a class block.'''
+        ...
+    
+
+
+class CodeVisitor(ast.NodeVisitor):
+    '''Base class for every NodeVisitors in `radon.visitors`. It implements a
+    couple utility class methods and a static method.
+    '''
+    @staticmethod
+    def get_name(obj):
+        '''Shorthand for ``obj.__class__.__name__``.'''
+        ...
+    
+    @classmethod
+    def from_code(cls, code, **kwargs): # -> Self:
+        '''Instanciate the class from source code (string object). The
+        `**kwargs` are directly passed to the `ast.NodeVisitor` constructor.
+        '''
+        ...
+    
+    @classmethod
+    def from_ast(cls, ast_node, **kwargs): # -> Self:
+        '''Instantiate the class from an AST node. The `**kwargs` are
+        directly passed to the `ast.NodeVisitor` constructor.
+        '''
+        ...
+    
+
+
+class ComplexityVisitor(CodeVisitor):
+    '''A visitor that keeps track of the cyclomatic complexity of
+    the elements.
+
+    :param to_method: If True, every function is treated as a method. In this
+        case the *classname* parameter is used as class name.
+    :param classname: Name of parent class.
+    :param off: If True, the starting value for the complexity is set to 1,
+        otherwise to 0.
+    '''
+    def __init__(self, to_method=..., classname=..., off=..., no_assert=...) -> None:
+        ...
+    
+    @property
+    def functions_complexity(self): # -> int:
+        '''The total complexity from all functions (i.e. the total number of
+        decision points + 1).
+
+        This is *not* the sum of all the complexity from the functions. Rather,
+        it's the complexity of the code *inside* all the functions.
+        '''
+        ...
+    
+    @property
+    def classes_complexity(self): # -> int:
+        '''The total complexity from all classes (i.e. the total number of
+        decision points + 1).
+        '''
+        ...
+    
+    @property
+    def total_complexity(self): # -> int:
+        '''The total complexity. Computed adding up the visitor complexity, the
+        functions complexity, and the classes complexity.
+        '''
+        ...
+    
+    @property
+    def blocks(self): # -> list[Any]:
+        '''All the blocks visited. These include: all the functions, the
+        classes and their methods. The returned list is not sorted.
+        '''
+        ...
+    
+    @property
+    def max_line(self): # -> float:
+        '''The maximum line number among the analyzed lines.'''
+        ...
+    
+    @max_line.setter
+    def max_line(self, value): # -> None:
+        '''The maximum line number among the analyzed lines.'''
+        ...
+    
+    def generic_visit(self, node): # -> None:
+        '''Main entry point for the visitor.'''
+        ...
+    
+    def visit_Assert(self, node): # -> None:
+        '''When visiting `assert` statements, the complexity is increased only
+        if the `no_assert` attribute is `False`.
+        '''
+        ...
+    
+    def visit_AsyncFunctionDef(self, node): # -> None:
+        '''Async function definition is the same thing as the synchronous
+        one.
+        '''
+        ...
+    
+    def visit_FunctionDef(self, node): # -> None:
+        '''When visiting functions a new visitor is created to recursively
+        analyze the function's body.
+        '''
+        ...
+    
+    def visit_ClassDef(self, node): # -> None:
+        '''When visiting classes a new visitor is created to recursively
+        analyze the class' body and methods.
+        '''
+        ...
+    
+
+
+class HalsteadVisitor(CodeVisitor):
+    '''Visitor that keeps track of operators and operands, in order to compute
+    Halstead metrics (see :func:`radon.metrics.h_visit`).
+    '''
+    types = ...
+    def __init__(self, context=...) -> None:
+        '''*context* is a string used to keep track the analysis' context.'''
+        ...
+    
+    @property
+    def distinct_operators(self): # -> int:
+        '''The number of distinct operators.'''
+        ...
+    
+    @property
+    def distinct_operands(self): # -> int:
+        '''The number of distinct operands.'''
+        ...
+    
+    def dispatch(meth): # -> Callable[..., None]:
+        '''This decorator does all the hard work needed for every node.
+
+        The decorated method must return a tuple of 4 elements:
+
+            * the number of operators
+            * the number of operands
+            * the operators seen (a sequence)
+            * the operands seen (a sequence)
+        '''
+        ...
+    
+    @dispatch
+    def visit_BinOp(self, node): # -> tuple[Literal[1], Literal[2], tuple[Any], tuple[expr, expr]]:
+        '''A binary operator.'''
+        ...
+    
+    @dispatch
+    def visit_UnaryOp(self, node): # -> tuple[Literal[1], Literal[1], tuple[Any], tuple[expr]]:
+        '''A unary operator.'''
+        ...
+    
+    @dispatch
+    def visit_BoolOp(self, node): # -> tuple[Literal[1], int, tuple[Any], list[expr]]:
+        '''A boolean operator.'''
+        ...
+    
+    @dispatch
+    def visit_AugAssign(self, node): # -> tuple[Literal[1], Literal[2], tuple[Any], tuple[Name | Attribute | Subscript, expr]]:
+        '''An augmented assign (contains an operator).'''
+        ...
+    
+    @dispatch
+    def visit_Compare(self, node): # -> tuple[int, int, map[Any], list[expr]]:
+        '''A comparison.'''
+        ...
+    
+    def visit_FunctionDef(self, node): # -> None:
+        '''When visiting functions, another visitor is created to recursively
+        analyze the function's body. We also track information on the function
+        itself.
+        '''
+        ...
+    
+    def visit_AsyncFunctionDef(self, node): # -> None:
+        '''Async functions are similar to standard functions, so treat them as
+        such.
+        '''
+        ...
+    
+
+