1class HookValidator:
 2    """Hook 合規性驗證器"""
 3
 4    # 驗證模式定義為類別常數
 5    VALID_NAME_PATTERNS = [
 6        r"^[a-z0-9](/python-advanced/02-metaprogramming/case-studies/declarative-validation/[a-z0-9\-_]*[a-z0-9])?\.py$",
 7    ]
 8
 9    HOOK_IO_PATTERNS = [
10        r"from\s+hook_io\s+import",
11        r"from\s+lib\.hook_io\s+import",
12    ]
13
14    def validate_hook(self, hook_path: str) -> ValidationResult:
15        """驗證單個 Hook 檔案"""
16        issues = []
17        issues.extend(self.check_naming_convention(hook_path))
18        issues.extend(self.check_lib_imports(content, hook_path))
19        issues.extend(self.check_output_format(content))
20        issues.extend(self.check_test_exists(hook_path))
21        return ValidationResult(hook_path=str(hook_path), issues=issues)
22
23    def check_naming_convention(self, hook_path: Path) -> List[ValidationIssue]:
24        """檢查命名規範"""
25        filename = hook_path.name
26        valid_name = any(
27            re.match(pattern, filename)
28            for pattern in self.VALID_NAME_PATTERNS
29        )
30        if not valid_name:
31            return [ValidationIssue(
32                level="warning",
33                message=f"檔案名稱不符合規範: {filename}",
34                suggestion="建議使用 snake-case 或 kebab-case 命名"
35            )]
36        return []

 1class HookConfig:
 2    """Hook 配置類別"""
 3    def __init__(self, name: str, event: str, command: str):
 4        # 驗證邏輯散落在 __init__ 中
 5        if not re.match(r"^[a-z0-9][a-z0-9\-_]*[a-z0-9]$", name):
 6            raise ValueError(f"無效的 Hook 名稱: {name}")
 7        if event not in ("PreToolUse", "PostToolUse", "Stop"):
 8            raise ValueError(f"無效的事件類型: {event}")
 9        if not command:
10            raise ValueError("命令不能為空")
11
12        self.name = name
13        self.event = event
14        self.command = command

 1import re
 2from typing import Any, Callable, Optional
 3
 4class ValidatedField:
 5    """
 6    驗證欄位 Descriptor
 7
 8    將驗證邏輯封裝在屬性定義中，
 9    賦值時自動執行驗證。
10    """
11
12    def __init__(
13        self,
14        validator: Callable[[Any], bool],
15        error_msg: str = "驗證失敗"
16    ):
17        """
18        Args:
19            validator: 驗證函式，接受值，返回 bool
20            error_msg: 驗證失敗時的錯誤訊息
21        """
22        self.validator = validator
23        self.error_msg = error_msg
24        # __set_name__ 會設定這些
25        self.name: str = ""
26        self.private_name: str = ""
27
28    def __set_name__(self, owner: type, name: str) -> None:
29        """
30        Python 3.6+ 自動呼叫，取得屬性名稱
31
32        Args:
33            owner: 擁有此 Descriptor 的類別
34            name: 屬性名稱
35        """
36        self.name = name
37        self.private_name = f"_{name}"
38
39    def __get__(self, obj: Any, objtype: type = None) -> Any:
40        """
41        讀取屬性時呼叫
42
43        Args:
44            obj: 實例（如果透過實例存取）
45            objtype: 類別
46
47        Returns:
48            屬性值，或透過類別存取時返回 Descriptor 本身
49        """
50        if obj is None:
51            return self  # 透過類別存取，返回 Descriptor
52        return getattr(obj, self.private_name, None)
53
54    def __set__(self, obj: Any, value: Any) -> None:
55        """
56        設定屬性時呼叫，執行驗證
57
58        Args:
59            obj: 實例
60            value: 要設定的值
61
62        Raises:
63            ValueError: 驗證失敗時
64        """
65        if not self.validator(value):
66            raise ValueError(f"{self.name}: {self.error_msg}")
67        setattr(obj, self.private_name, value)

 1class PatternField(ValidatedField):
 2    """
 3    正則表達式驗證欄位
 4
 5    簡化常見的模式匹配驗證。
 6    """
 7
 8    def __init__(self, pattern: str, error_msg: str = "格式不符"):
 9        """
10        Args:
11            pattern: 正則表達式模式
12            error_msg: 驗證失敗時的錯誤訊息
13        """
14        self.pattern = re.compile(pattern)
15        super().__init__(
16            validator=lambda v: bool(self.pattern.match(str(v))),
17            error_msg=error_msg
18        )
19
20class ChoiceField(ValidatedField):
21    """
22    選項驗證欄位
23
24    限制值必須在指定選項中。
25    """
26
27    def __init__(self, choices: tuple, error_msg: str = "無效的選項"):
28        """
29        Args:
30            choices: 允許的選項
31            error_msg: 驗證失敗時的錯誤訊息
32        """
33        self.choices = choices
34        super().__init__(
35            validator=lambda v: v in self.choices,
36            error_msg=f"{error_msg}，必須是: {', '.join(str(c) for c in choices)}"
37        )
38
39class NonEmptyField(ValidatedField):
40    """
41    非空驗證欄位
42
43    確保值不為空。
44    """
45
46    def __init__(self, error_msg: str = "不能為空"):
47        super().__init__(
48            validator=lambda v: bool(v),
49            error_msg=error_msg
50        )
51
52class RangeField(ValidatedField):
53    """
54    範圍驗證欄位
55
56    確保數值在指定範圍內。
57    """
58
59    def __init__(
60        self,
61        min_val: Optional[float] = None,
62        max_val: Optional[float] = None,
63        error_msg: str = "超出範圍"
64    ):
65        """
66        Args:
67            min_val: 最小值（None 表示無下限）
68            max_val: 最大值（None 表示無上限）
69            error_msg: 驗證失敗時的錯誤訊息
70        """
71        self.min_val = min_val
72        self.max_val = max_val
73
74        def validator(v):
75            if min_val is not None and v < min_val:
76                return False
77            if max_val is not None and v > max_val:
78                return False
79            return True
80
81        range_desc = []
82        if min_val is not None:
83            range_desc.append(f">= {min_val}")
84        if max_val is not None:
85            range_desc.append(f"<= {max_val}")
86
87        super().__init__(
88            validator=validator,
89            error_msg=f"{error_msg}，必須 {' 且 '.join(range_desc)}"
90        )

 1class HookConfig:
 2    """
 3    Hook 配置類別 - 宣告式驗證版本
 4
 5    驗證規則直接在類別定義中可見。
 6    """
 7
 8    # 宣告式驗證：欄位定義即驗證規則
 9    name = PatternField(
10        r"^[a-z0-9][a-z0-9\-_]*[a-z0-9]$",
11        "Hook 名稱必須是小寫字母、數字、連字號或底線，且不能以連字號開頭或結尾"
12    )
13
14    event = ChoiceField(
15        ("PreToolUse", "PostToolUse", "Stop", "SessionStart", "SessionEnd"),
16        "無效的事件類型"
17    )
18
19    command = NonEmptyField("命令不能為空")
20
21    timeout = RangeField(
22        min_val=0,
23        max_val=300,
24        error_msg="超時時間無效"
25    )
26
27    def __init__(
28        self,
29        name: str,
30        event: str,
31        command: str,
32        timeout: int = 30
33    ):
34        """
35        初始化 Hook 配置
36
37        Args:
38            name: Hook 名稱
39            event: 事件類型
40            command: 執行的命令
41            timeout: 超時時間（秒）
42
43        驗證會在賦值時自動執行。
44        """
45        self.name = name      # 自動驗證名稱格式
46        self.event = event    # 自動驗證事件類型
47        self.command = command  # 自動驗證非空
48        self.timeout = timeout  # 自動驗證範圍
49
50    def __repr__(self) -> str:
51        return (
52            f"HookConfig(name={self.name!r}, event={self.event!r}, "
53            f"command={self.command!r}, timeout={self.timeout})"
54        )

  1#!/usr/bin/env python3
  2"""
  3宣告式驗證 - 完整範例
  4
  5展示如何用 Descriptor Protocol 實現宣告式驗證。
  6"""
  7
  8import re
  9from typing import Any, Callable, Optional
 10
 11# ===== Descriptor 定義 =====
 12
 13class ValidatedField:
 14    """驗證欄位 Descriptor 基類"""
 15
 16    def __init__(
 17        self,
 18        validator: Callable[[Any], bool],
 19        error_msg: str = "驗證失敗"
 20    ):
 21        self.validator = validator
 22        self.error_msg = error_msg
 23        self.name: str = ""
 24        self.private_name: str = ""
 25
 26    def __set_name__(self, owner: type, name: str) -> None:
 27        self.name = name
 28        self.private_name = f"_{name}"
 29
 30    def __get__(self, obj: Any, objtype: type = None) -> Any:
 31        if obj is None:
 32            return self
 33        return getattr(obj, self.private_name, None)
 34
 35    def __set__(self, obj: Any, value: Any) -> None:
 36        if not self.validator(value):
 37            raise ValueError(f"{self.name}: {self.error_msg}")
 38        setattr(obj, self.private_name, value)
 39
 40class PatternField(ValidatedField):
 41    """正則表達式驗證欄位"""
 42
 43    def __init__(self, pattern: str, error_msg: str = "格式不符"):
 44        self.pattern = re.compile(pattern)
 45        super().__init__(
 46            validator=lambda v: bool(self.pattern.match(str(v))),
 47            error_msg=error_msg
 48        )
 49
 50class ChoiceField(ValidatedField):
 51    """選項驗證欄位"""
 52
 53    def __init__(self, choices: tuple, error_msg: str = "無效的選項"):
 54        self.choices = choices
 55        super().__init__(
 56            validator=lambda v: v in self.choices,
 57            error_msg=f"{error_msg}，必須是: {', '.join(str(c) for c in choices)}"
 58        )
 59
 60class NonEmptyField(ValidatedField):
 61    """非空驗證欄位"""
 62
 63    def __init__(self, error_msg: str = "不能為空"):
 64        super().__init__(
 65            validator=lambda v: bool(v),
 66            error_msg=error_msg
 67        )
 68
 69class RangeField(ValidatedField):
 70    """範圍驗證欄位"""
 71
 72    def __init__(
 73        self,
 74        min_val: Optional[float] = None,
 75        max_val: Optional[float] = None,
 76        error_msg: str = "超出範圍"
 77    ):
 78        self.min_val = min_val
 79        self.max_val = max_val
 80
 81        def validator(v):
 82            if min_val is not None and v < min_val:
 83                return False
 84            if max_val is not None and v > max_val:
 85                return False
 86            return True
 87
 88        range_desc = []
 89        if min_val is not None:
 90            range_desc.append(f">= {min_val}")
 91        if max_val is not None:
 92            range_desc.append(f"<= {max_val}")
 93
 94        super().__init__(
 95            validator=validator,
 96            error_msg=f"{error_msg}，必須 {' 且 '.join(range_desc)}"
 97        )
 98
 99# ===== 使用範例 =====
100
101class HookConfig:
102    """Hook 配置類別 - 宣告式驗證"""
103
104    name = PatternField(
105        r"^[a-z0-9][a-z0-9\-_]*[a-z0-9]$",
106        "Hook 名稱格式無效"
107    )
108
109    event = ChoiceField(
110        ("PreToolUse", "PostToolUse", "Stop", "SessionStart", "SessionEnd"),
111        "無效的事件類型"
112    )
113
114    command = NonEmptyField("命令不能為空")
115
116    timeout = RangeField(min_val=0, max_val=300, error_msg="超時時間無效")
117
118    def __init__(self, name: str, event: str, command: str, timeout: int = 30):
119        self.name = name
120        self.event = event
121        self.command = command
122        self.timeout = timeout
123
124    def __repr__(self) -> str:
125        return f"HookConfig({self.name!r}, {self.event!r}, {self.command!r})"
126
127# ===== 測試 =====
128
129if __name__ == "__main__":
130    # 正確的配置
131    config = HookConfig(
132        name="check-format",
133        event="PreToolUse",
134        command="python check.py"
135    )
136    print(f"建立成功: {config}")
137
138    # 修改屬性也會驗證
139    config.timeout = 60
140    print(f"修改 timeout: {config.timeout}")
141
142    # 驗證失敗的例子
143    try:
144        bad_config = HookConfig(
145            name="Check-Format",  # 錯誤：大寫
146            event="PreToolUse",
147            command="python check.py"
148        )
149    except ValueError as e:
150        print(f"驗證失敗: {e}")
151
152    try:
153        config.event = "InvalidEvent"  # 錯誤：無效的事件
154    except ValueError as e:
155        print(f"驗證失敗: {e}")
156
157    try:
158        config.timeout = 500  # 錯誤：超出範圍
159    except ValueError as e:
160        print(f"驗證失敗: {e}")

 1# 正確的配置
 2>>> config = HookConfig(
 3...     name="check-format",
 4...     event="PreToolUse",
 5...     command="python check.py"
 6... )
 7>>> config
 8HookConfig('check-format', 'PreToolUse', 'python check.py')
 9
10# 修改屬性也會驗證
11>>> config.timeout = 60
12>>> config.timeout
1360
14
15# 驗證失敗
16>>> config.name = "Invalid Name"
17ValueError: name: Hook 名稱格式無效
18
19>>> config.event = "BadEvent"
20ValueError: event: 無效的事件類型，必須是: PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd
21
22>>> config.timeout = -1
23ValueError: timeout: 超時時間無效，必須 >= 0 且 <= 300

 1from dataclasses import dataclass, field
 2
 3@dataclass
 4class HookConfigDataclass:
 5    """使用 dataclass + Descriptor"""
 6
 7    # Descriptor 欄位需要特殊處理
 8    _name: str = field(init=False, repr=False)
 9    _event: str = field(init=False, repr=False)
10
11    # 公開欄位
12    name: str = field(default="")
13    event: str = field(default="PreToolUse")
14
15    # Descriptor 定義（類別變數）
16    name = PatternField(r"^[a-z0-9][a-z0-9\-_]*[a-z0-9]$", "無效的名稱")
17    event = ChoiceField(("PreToolUse", "PostToolUse", "Stop"), "無效的事件")
18
19    def __post_init__(self):
20        # 觸發 Descriptor 驗證
21        self.name = self.name
22        self.event = self.event

 1class HookValidator:
 2    """Hook 合規性驗證器"""
 3
 4    def validate_hook(self, hook_path: str) -> ValidationResult:
 5        """驗證單個 Hook 檔案"""
 6        # ... 前置處理 ...
 7
 8        # 執行各項檢查 - 手動呼叫每個 check 方法
 9        issues = []
10        issues.extend(self.check_naming_convention(hook_path))
11        issues.extend(self.check_lib_imports(content, hook_path))
12        issues.extend(self.check_output_format(content))
13        issues.extend(self.check_test_exists(hook_path))
14
15        return ValidationResult(hook_path=str(hook_path), issues=issues)
16
17    def check_naming_convention(self, hook_path: Path) -> List[ValidationIssue]:
18        """檢查命名規範"""
19        # ... 實作 ...
20
21    def check_lib_imports(self, content: str, hook_path: Path) -> List[ValidationIssue]:
22        """檢查共用模組導入"""
23        # ... 實作 ...
24
25    def check_output_format(self, content: str) -> List[ValidationIssue]:
26        """檢查 Hook 輸出格式"""
27        # ... 實作 ...
28
29    def check_test_exists(self, hook_path: Path) -> List[ValidationIssue]:
30        """檢查對應的測試檔案是否存在"""
31        # ... 實作 ...

 1from functools import wraps
 2from typing import Callable, Optional
 3
 4def check(
 5    priority: int = 100,
 6    enabled: bool = True,
 7    description: str = ""
 8) -> Callable:
 9    """
10    Decorator to mark a method as a checker.
11
12    Args:
13        priority: Execution order (lower runs first)
14        enabled: Whether this check is enabled by default
15        description: Human-readable description
16
17    Example:
18        @check(priority=10, description="Validate filename format")
19        def check_naming(self, hook_path):
20            ...
21    """
22    def decorator(func: Callable) -> Callable:
23        # Store metadata on the function object
24        func._is_checker = True
25        func._checker_priority = priority
26        func._checker_enabled = enabled
27        func._checker_description = description or func.__doc__ or func.__name__
28
29        @wraps(func)
30        def wrapper(*args, **kwargs):
31            return func(*args, **kwargs)
32
33        # Copy metadata to wrapper
34        wrapper._is_checker = True
35        wrapper._checker_priority = priority
36        wrapper._checker_enabled = enabled
37        wrapper._checker_description = description or func.__doc__ or func.__name__
38
39        return wrapper
40    return decorator

 1class Validator:
 2    @check(priority=10, description="Check filename format")
 3    def check_naming_convention(self, hook_path):
 4        """檢查命名規範"""
 5        ...
 6
 7    @check(priority=20, description="Check library imports")
 8    def check_lib_imports(self, content, hook_path):
 9        """檢查共用模組導入"""
10        ...

 1class CheckerMeta(type):
 2    """
 3    Metaclass that automatically collects methods marked with @check.
 4
 5    When a class is created, this metaclass:
 6    1. Scans all methods for the _is_checker attribute
 7    2. Collects them into a _checkers registry
 8    3. Sorts by priority for execution order
 9    """
10
11    def __new__(mcs, name: str, bases: tuple, namespace: dict):
12        # Create the class first
13        cls = super().__new__(mcs, name, bases, namespace)
14
15        # Collect checkers from parent classes
16        inherited_checkers = {}
17        for base in bases:
18            if hasattr(base, '_checkers'):
19                inherited_checkers.update(base._checkers)
20
21        # Collect checkers from current class
22        current_checkers = {}
23        for attr_name, attr_value in namespace.items():
24            if callable(attr_value) and getattr(attr_value, '_is_checker', False):
25                current_checkers[attr_name] = {
26                    'method': attr_name,
27                    'priority': attr_value._checker_priority,
28                    'enabled': attr_value._checker_enabled,
29                    'description': attr_value._checker_description,
30                }
31
32        # Merge: current class can override parent checkers
33        all_checkers = {**inherited_checkers, **current_checkers}
34
35        # Store as class attribute
36        cls._checkers = all_checkers
37
38        return cls

 1class CheckerBase(metaclass=CheckerMeta):
 2    """
 3    Base class for validators with auto-registration.
 4
 5    Provides run_all_checks() to execute registered checkers.
 6    """
 7
 8    def get_sorted_checkers(self) -> list:
 9        """
10        Get all enabled checkers sorted by priority.
11
12        Returns:
13            List of (method_name, checker_info) tuples
14        """
15        checkers = [
16            (name, info)
17            for name, info in self._checkers.items()
18            if info['enabled']
19        ]
20        # Sort by priority (lower number = higher priority)
21        return sorted(checkers, key=lambda x: x[1]['priority'])
22
23    def run_all_checks(self, *args, **kwargs) -> list:
24        """
25        Run all enabled checkers in priority order.
26
27        Args:
28            *args, **kwargs: Arguments passed to each checker
29
30        Returns:
31            Combined list of issues from all checkers
32        """
33        all_issues = []
34
35        for method_name, info in self.get_sorted_checkers():
36            method = getattr(self, method_name)
37            try:
38                issues = method(*args, **kwargs)
39                if issues:
40                    all_issues.extend(issues)
41            except Exception as e:
42                # Optionally handle checker errors
43                all_issues.append({
44                    'level': 'error',
45                    'message': f"Checker {method_name} failed: {e}"
46                })
47
48        return all_issues

 1class CheckerBase(metaclass=CheckerMeta):
 2    """
 3    Base class for validators with auto-registration.
 4    """
 5
 6    def __init__(self):
 7        # Instance-level override for checker states
 8        self._checker_overrides = {}
 9
10    def enable_checker(self, checker_name: str) -> None:
11        """
12        Enable a specific checker for this instance.
13
14        Args:
15            checker_name: Name of the checker method
16        """
17        if checker_name not in self._checkers:
18            raise ValueError(f"Unknown checker: {checker_name}")
19        self._checker_overrides[checker_name] = True
20
21    def disable_checker(self, checker_name: str) -> None:
22        """
23        Disable a specific checker for this instance.
24
25        Args:
26            checker_name: Name of the checker method
27        """
28        if checker_name not in self._checkers:
29            raise ValueError(f"Unknown checker: {checker_name}")
30        self._checker_overrides[checker_name] = False
31
32    def is_checker_enabled(self, checker_name: str) -> bool:
33        """
34        Check if a specific checker is enabled.
35
36        Instance overrides take precedence over class defaults.
37        """
38        if checker_name in self._checker_overrides:
39            return self._checker_overrides[checker_name]
40        return self._checkers.get(checker_name, {}).get('enabled', False)
41
42    def get_sorted_checkers(self) -> list:
43        """Get all enabled checkers sorted by priority."""
44        checkers = [
45            (name, info)
46            for name, info in self._checkers.items()
47            if self.is_checker_enabled(name)
48        ]
49        return sorted(checkers, key=lambda x: x[1]['priority'])
50
51    def list_checkers(self) -> list:
52        """
53        List all available checkers with their status.
54
55        Returns:
56            List of dicts with checker information
57        """
58        result = []
59        for name, info in sorted(
60            self._checkers.items(),
61            key=lambda x: x[1]['priority']
62        ):
63            result.append({
64                'name': name,
65                'priority': info['priority'],
66                'enabled': self.is_checker_enabled(name),
67                'description': info['description'],
68            })
69        return result

  1#!/usr/bin/env python3
  2"""
  3Auto-registration pattern using Metaclass.
  4
  5This module demonstrates how to automatically register checker methods
  6using a combination of decorators and metaclasses.
  7"""
  8
  9from dataclasses import dataclass, field
 10from functools import wraps
 11from pathlib import Path
 12from typing import Callable, List, Optional, Any
 13import re
 14
 15# ===== Data Classes =====
 16
 17@dataclass
 18class ValidationIssue:
 19    """Represents a validation issue."""
 20    level: str  # "error" | "warning" | "info"
 21    message: str
 22    line: Optional[int] = None
 23    suggestion: Optional[str] = None
 24
 25@dataclass
 26class ValidationResult:
 27    """Validation result for a single target."""
 28    target: str
 29    issues: List[ValidationIssue] = field(default_factory=list)
 30
 31    @property
 32    def is_valid(self) -> bool:
 33        """True if no errors found."""
 34        return not any(issue.level == "error" for issue in self.issues)
 35
 36# ===== Decorator =====
 37
 38def check(
 39    priority: int = 100,
 40    enabled: bool = True,
 41    description: str = ""
 42) -> Callable:
 43    """
 44    Decorator to mark a method as a checker.
 45
 46    Args:
 47        priority: Execution order (lower runs first)
 48        enabled: Whether this check is enabled by default
 49        description: Human-readable description
 50    """
 51    def decorator(func: Callable) -> Callable:
 52        @wraps(func)
 53        def wrapper(*args, **kwargs):
 54            return func(*args, **kwargs)
 55
 56        # Store metadata
 57        wrapper._is_checker = True
 58        wrapper._checker_priority = priority
 59        wrapper._checker_enabled = enabled
 60        wrapper._checker_description = description or func.__doc__ or func.__name__
 61
 62        return wrapper
 63    return decorator
 64
 65# ===== Metaclass =====
 66
 67class CheckerMeta(type):
 68    """
 69    Metaclass that automatically collects @check decorated methods.
 70    """
 71
 72    def __new__(mcs, name: str, bases: tuple, namespace: dict):
 73        cls = super().__new__(mcs, name, bases, namespace)
 74
 75        # Inherit checkers from parent classes
 76        inherited_checkers = {}
 77        for base in bases:
 78            if hasattr(base, '_checkers'):
 79                inherited_checkers.update(base._checkers)
 80
 81        # Collect checkers from current class
 82        current_checkers = {}
 83        for attr_name, attr_value in namespace.items():
 84            if callable(attr_value) and getattr(attr_value, '_is_checker', False):
 85                current_checkers[attr_name] = {
 86                    'method': attr_name,
 87                    'priority': attr_value._checker_priority,
 88                    'enabled': attr_value._checker_enabled,
 89                    'description': attr_value._checker_description,
 90                }
 91
 92        # Merge checkers
 93        cls._checkers = {**inherited_checkers, **current_checkers}
 94
 95        return cls
 96
 97# ===== Base Class =====
 98
 99class CheckerBase(metaclass=CheckerMeta):
100    """
101    Base class providing auto-registration functionality.
102    """
103
104    def __init__(self):
105        self._checker_overrides = {}
106
107    def enable_checker(self, name: str) -> None:
108        """Enable a checker for this instance."""
109        if name not in self._checkers:
110            raise ValueError(f"Unknown checker: {name}")
111        self._checker_overrides[name] = True
112
113    def disable_checker(self, name: str) -> None:
114        """Disable a checker for this instance."""
115        if name not in self._checkers:
116            raise ValueError(f"Unknown checker: {name}")
117        self._checker_overrides[name] = False
118
119    def is_checker_enabled(self, name: str) -> bool:
120        """Check if a checker is enabled."""
121        if name in self._checker_overrides:
122            return self._checker_overrides[name]
123        return self._checkers.get(name, {}).get('enabled', False)
124
125    def get_sorted_checkers(self) -> list:
126        """Get enabled checkers sorted by priority."""
127        return sorted(
128            [(n, i) for n, i in self._checkers.items() if self.is_checker_enabled(n)],
129            key=lambda x: x[1]['priority']
130        )
131
132    def list_checkers(self) -> list:
133        """List all checkers with their status."""
134        return [
135            {
136                'name': name,
137                'priority': info['priority'],
138                'enabled': self.is_checker_enabled(name),
139                'description': info['description'],
140            }
141            for name, info in sorted(
142                self._checkers.items(),
143                key=lambda x: x[1]['priority']
144            )
145        ]
146
147# ===== Implementation Example =====
148
149class HookValidator(CheckerBase):
150    """
151    Hook validator with auto-registered checkers.
152
153    Checkers are automatically discovered and executed in priority order.
154    """
155
156    # Pattern constants
157    VALID_NAME_PATTERN = r"^[a-z0-9](/python-advanced/02-metaprogramming/case-studies/auto-registration/[a-z0-9\-_]*[a-z0-9])?\.py$"
158    HOOK_IO_PATTERNS = [
159        r"from\s+hook_io\s+import",
160        r"from\s+lib\.hook_io\s+import",
161    ]
162    BAD_OUTPUT_PATTERNS = [
163        r'print\s*\(\s*json\.dumps\s*\(',
164    ]
165
166    def __init__(self, project_root: Optional[str] = None):
167        super().__init__()
168        self.project_root = Path(project_root) if project_root else Path.cwd()
169
170    def validate(self, hook_path: str) -> ValidationResult:
171        """
172        Validate a hook file by running all enabled checkers.
173
174        Args:
175            hook_path: Path to the hook file
176
177        Returns:
178            ValidationResult with all issues found
179        """
180        path = Path(hook_path)
181        if not path.is_absolute():
182            path = self.project_root / path
183
184        # Read file content
185        try:
186            content = path.read_text(encoding='utf-8')
187        except Exception as e:
188            return ValidationResult(
189                target=str(path),
190                issues=[ValidationIssue(
191                    level="error",
192                    message=f"Cannot read file: {e}"
193                )]
194            )
195
196        # Prepare context for checkers
197        context = {
198            'path': path,
199            'content': content,
200            'filename': path.name,
201        }
202
203        # Run all enabled checkers
204        all_issues = []
205        for method_name, _ in self.get_sorted_checkers():
206            method = getattr(self, method_name)
207            try:
208                issues = method(context)
209                if issues:
210                    all_issues.extend(issues)
211            except Exception as e:
212                all_issues.append(ValidationIssue(
213                    level="error",
214                    message=f"Checker '{method_name}' crashed: {e}"
215                ))
216
217        return ValidationResult(target=str(path), issues=all_issues)
218
219    @check(priority=10, description="Check filename format")
220    def check_naming_convention(self, ctx: dict) -> List[ValidationIssue]:
221        """Validate hook filename follows naming convention."""
222        issues = []
223        filename = ctx['filename']
224
225        if not re.match(self.VALID_NAME_PATTERN, filename):
226            issues.append(ValidationIssue(
227                level="warning",
228                message=f"Filename '{filename}' doesn't follow naming convention",
229                suggestion="Use snake_case or kebab-case, e.g., check_format.py"
230            ))
231
232        return issues
233
234    @check(priority=20, description="Check hook_io import")
235    def check_lib_imports(self, ctx: dict) -> List[ValidationIssue]:
236        """Check if hook_io module is properly imported."""
237        issues = []
238        content = ctx['content']
239
240        has_import = any(
241            re.search(pattern, content)
242            for pattern in self.HOOK_IO_PATTERNS
243        )
244
245        if not has_import:
246            issues.append(ValidationIssue(
247                level="warning",
248                message="hook_io module not imported",
249                suggestion="Add: from hook_io import read_hook_input, write_hook_output"
250            ))
251
252        return issues
253
254    @check(priority=30, description="Check output format")
255    def check_output_format(self, ctx: dict) -> List[ValidationIssue]:
256        """Check if proper output functions are used."""
257        issues = []
258        content = ctx['content']
259
260        for pattern in self.BAD_OUTPUT_PATTERNS:
261            if re.search(pattern, content):
262                issues.append(ValidationIssue(
263                    level="warning",
264                    message="Using print(json.dumps(...)) instead of write_hook_output()",
265                    suggestion="Replace with: write_hook_output(output_dict)"
266                ))
267                break
268
269        return issues
270
271    @check(priority=40, enabled=False, description="Check test file exists")
272    def check_test_exists(self, ctx: dict) -> List[ValidationIssue]:
273        """Check if corresponding test file exists."""
274        issues = []
275        hook_name = ctx['path'].stem
276        test_name = f"test_{hook_name.replace('-', '_')}.py"
277
278        test_path = self.project_root / ".claude" / "lib" / "tests" / test_name
279        if not test_path.exists():
280            issues.append(ValidationIssue(
281                level="info",
282                message=f"No test file found: {test_name}",
283                suggestion=f"Create test at: {test_path}"
284            ))
285
286        return issues
287
288# ===== Extended Example: Subclass =====
289
290class StrictHookValidator(HookValidator):
291    """
292    Extended validator with additional checks.
293
294    Inherits all checks from HookValidator and adds more.
295    """
296
297    @check(priority=15, description="Check shebang line")
298    def check_shebang(self, ctx: dict) -> List[ValidationIssue]:
299        """Check if file starts with proper shebang."""
300        issues = []
301        content = ctx['content']
302
303        if not content.startswith('#!/usr/bin/env python'):
304            issues.append(ValidationIssue(
305                level="info",
306                message="Missing shebang line",
307                suggestion="Add: #!/usr/bin/env python3"
308            ))
309
310        return issues
311
312    @check(priority=25, description="Check docstring exists")
313    def check_docstring(self, ctx: dict) -> List[ValidationIssue]:
314        """Check if module has a docstring."""
315        issues = []
316        content = ctx['content']
317
318        # Simple check: look for triple quotes near the start
319        lines = content.split('\n')[:10]  # First 10 lines
320        has_docstring = any('"""' in line or "'''" in line for line in lines)
321
322        if not has_docstring:
323            issues.append(ValidationIssue(
324                level="info",
325                message="Module docstring not found",
326                suggestion="Add a docstring at the top of the file"
327            ))
328
329        return issues
330
331# ===== Demo =====
332
333if __name__ == "__main__":
334    print("=" * 60)
335    print("Auto-Registration Demo")
336    print("=" * 60)
337
338    # Create validator
339    validator = HookValidator()
340
341    # List all registered checkers
342    print("\n[Registered Checkers]")
343    for checker in validator.list_checkers():
344        status = "ON" if checker['enabled'] else "OFF"
345        print(f"  [{status}] {checker['name']} (priority: {checker['priority']})")
346        print(f"        {checker['description']}")
347
348    # Enable disabled checker
349    print("\n[Enable check_test_exists]")
350    validator.enable_checker('check_test_exists')
351    for checker in validator.list_checkers():
352        if checker['name'] == 'check_test_exists':
353            status = "ON" if checker['enabled'] else "OFF"
354            print(f"  [{status}] {checker['name']}")
355
356    # Demo with extended validator
357    print("\n[Extended Validator - StrictHookValidator]")
358    strict_validator = StrictHookValidator()
359    for checker in strict_validator.list_checkers():
360        status = "ON" if checker['enabled'] else "OFF"
361        print(f"  [{status}] {checker['name']} (priority: {checker['priority']})")
362
363    print("\n" + "=" * 60)

 1# Create validator instance
 2validator = HookValidator(project_root="/path/to/project")
 3
 4# List available checkers
 5for checker in validator.list_checkers():
 6    print(f"[{'ON' if checker['enabled'] else 'OFF'}] {checker['name']}")
 7
 8# Output:
 9# [ON] check_naming_convention
10# [ON] check_lib_imports
11# [ON] check_output_format
12# [OFF] check_test_exists
13
14# Enable/disable checkers dynamically
15validator.enable_checker('check_test_exists')
16validator.disable_checker('check_output_format')
17
18# Validate a hook file
19result = validator.validate(".claude/hooks/my-hook.py")
20print(f"Valid: {result.is_valid}")
21for issue in result.issues:
22    print(f"  [{issue.level}] {issue.message}")
23
24# Create extended validator with more checks
25strict = StrictHookValidator()
26print(f"Total checkers: {len(strict.list_checkers())}")  # Inherits parent's checkers

 1class CheckerBase:
 2    """
 3    Base class using __init_subclass__ for auto-registration.
 4
 5    Simpler than metaclass, but less powerful.
 6    """
 7    _checkers = {}
 8
 9    def __init_subclass__(cls, **kwargs):
10        super().__init_subclass__(**kwargs)
11
12        # Collect checkers from this subclass
13        for attr_name in dir(cls):
14            attr = getattr(cls, attr_name, None)
15            if callable(attr) and getattr(attr, '_is_checker', False):
16                cls._checkers[attr_name] = {
17                    'method': attr_name,
18                    'priority': attr._checker_priority,
19                    'enabled': attr._checker_enabled,
20                    'description': attr._checker_description,
21                }
22
23class HookValidator(CheckerBase):
24    """Validator using __init_subclass__."""
25
26    @check(priority=10)
27    def check_naming(self, ctx):
28        """Check naming convention."""
29        pass
30
31    @check(priority=20)
32    def check_imports(self, ctx):
33        """Check imports."""
34        pass