moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/hooks/moai/lib/tag_parser.py

@@ -0,0 +1,176 @@
+"""TAG parser module for TAG System v2.0.
+
+Implements T2: TAG Parser for extracting TAG annotations from
+Python source code comments using AST parsing.
+"""
+
+from __future__ import annotations
+
+import ast
+import logging
+from pathlib import Path
+from typing import List
+
+from . import tag_validator
+
+logger = logging.getLogger(__name__)
+
+
+def extract_tags_from_source(source: str, file_path: Path) -> List[tag_validator.TAG]:
+    """Extract all @SPEC TAGs from Python source code.
+
+    Args:
+        source: Python source code as string
+        file_path: Path to the source file
+
+    Returns:
+        List of TAG objects found in the source
+
+    Examples:
+        >>> source = "# @SPEC SPEC-AUTH-001\\ndef func(): pass"
+        >>> tags = extract_tags_from_source(source, Path("test.py"))
+        >>> len(tags)
+        1
+    """
+    tags: List[tag_validator.TAG] = []
+
+    if not isinstance(source, str):
+        return tags
+
+    # Split source into lines and extract TAGs from comments
+    lines = source.splitlines()
+
+    for line_number, line in enumerate(lines, start=1):
+        # Handle both standalone comments and inline comments
+        # Find the comment portion if it exists
+        comment_start = line.find("#")
+
+        if comment_start == -1:
+            # No comment in this line
+            continue
+
+        # Extract the comment portion (from # to end of line)
+        comment_portion = line[comment_start:]
+
+        # Parse TAG from comment
+        tag = tag_validator.parse_tag_string(comment_portion, file_path, line_number)
+
+        if tag is not None:
+            tags.append(tag)
+
+    return tags
+
+
+def extract_tags_from_file(file_path: Path) -> List[tag_validator.TAG]:
+    """Extract all @SPEC TAGs from a Python file.
+
+    Args:
+        file_path: Path to the Python file
+
+    Returns:
+        List of TAG objects found in the file, empty list if file doesn't exist or has errors
+
+    Examples:
+        >>> tags = extract_tags_from_file(Path("auth.py"))
+        >>> len(tags)
+        2
+    """
+    if not isinstance(file_path, Path):
+        file_path = Path(file_path)
+
+    # Check if file exists
+    if not file_path.exists():
+        logger.warning(f"File not found: {file_path}")
+        return []
+
+    # Check if file is readable
+    if not file_path.is_file():
+        logger.warning(f"Not a file: {file_path}")
+        return []
+
+    try:
+        # Read file content
+        source = file_path.read_text(encoding="utf-8")
+
+        # Validate Python syntax
+        try:
+            ast.parse(source)
+        except SyntaxError as e:
+            logger.warning(f"Syntax error in {file_path}: {e}")
+            return []
+
+        # Extract TAGs
+        return extract_tags_from_source(source, file_path)
+
+    except Exception as e:
+        logger.error(f"Error reading file {file_path}: {e}")
+        return []
+
+
+def extract_tags_from_files(file_paths: List[Path]) -> List[tag_validator.TAG]:
+    """Extract TAGs from multiple files.
+
+    Args:
+        file_paths: List of file paths to process
+
+    Returns:
+        List of all TAGs found across all files
+
+    Examples:
+        >>> files = [Path("a.py"), Path("b.py")]
+        >>> tags = extract_tags_from_files(files)
+        >>> len(tags)
+        5
+    """
+    all_tags: List[tag_validator.TAG] = []
+
+    for file_path in file_paths:
+        tags = extract_tags_from_file(file_path)
+        all_tags.extend(tags)
+
+    return all_tags
+
+
+def extract_tags_from_directory(
+    directory: Path,
+    pattern: str = "*.py",
+    recursive: bool = True,
+) -> List[tag_validator.TAG]:
+    """Extract TAGs from all Python files in a directory.
+
+    Args:
+        directory: Directory path to search
+        pattern: File pattern to match (default: "*.py")
+        recursive: Whether to search recursively (default: True)
+
+    Returns:
+        List of all TAGs found in matching files
+
+    Examples:
+        >>> tags = extract_tags_from_directory(Path("src/"))
+        >>> len(tags)
+        42
+    """
+    if not isinstance(directory, Path):
+        directory = Path(directory)
+
+    if not directory.exists() or not directory.is_dir():
+        logger.warning(f"Not a directory: {directory}")
+        return []
+
+    # Find matching files
+    if recursive:
+        files = list(directory.rglob(pattern))
+    else:
+        files = list(directory.glob(pattern))
+
+    # Extract TAGs from all files
+    return extract_tags_from_files(files)
+
+
+__all__ = [
+    "extract_tags_from_source",
+    "extract_tags_from_file",
+    "extract_tags_from_files",
+    "extract_tags_from_directory",
+]

moai_adk/templates/.claude/hooks/moai/lib/tag_validator.py

@@ -0,0 +1,200 @@
+"""TAG validator module for TAG System v2.0.
+
+Implements T1: TAG Pattern Definition with format validation,
+SPEC-ID validation, and verb validation.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Tuple
+
+# TAG pattern: @SPEC SPEC-ID [verb]
+# SPEC-ID format: SPEC-{DOMAIN}-{NUMBER}
+# DOMAIN: Uppercase letters, at least 1 char
+# NUMBER: 3 digits
+SPEC_ID_PATTERN = re.compile(r"^SPEC-[A-Z]+-\d{3}$")
+
+# Valid TAG verbs
+VALID_VERBS = {"impl", "verify", "depends", "related"}
+
+# Default verb when not specified
+DEFAULT_VERB = "impl"
+
+
+@dataclass(frozen=True)
+class TAG:
+    """Represents a single TAG annotation.
+
+    Attributes:
+        spec_id: SPEC identifier (e.g., "SPEC-AUTH-001")
+        verb: TAG relationship verb (impl, verify, depends, related)
+        file_path: Path to the file containing the TAG
+        line: Line number where TAG appears
+    """
+
+    spec_id: str
+    file_path: Path
+    line: int
+    verb: str = field(default=DEFAULT_VERB)
+
+    def __post_init__(self) -> None:
+        """Validate TAG fields after initialization."""
+        # Normalize verb to lowercase
+        if self.verb != self.verb.lower():
+            object.__setattr__(self, "verb", self.verb.lower())
+
+
+def validate_spec_id_format(spec_id: str) -> bool:
+    """Validate SPEC-ID format: SPEC-{DOMAIN}-{NUMBER}.
+
+    Args:
+        spec_id: SPEC identifier to validate
+
+    Returns:
+        True if SPEC-ID matches required format, False otherwise
+
+    Examples:
+        >>> validate_spec_id_format("SPEC-AUTH-001")
+        True
+        >>> validate_spec_id_format("spec-auth-001")
+        False
+        >>> validate_spec_id_format("SPEC-AUTH-1")
+        False
+    """
+    return isinstance(spec_id, str) and bool(SPEC_ID_PATTERN.match(spec_id))
+
+
+def validate_verb(verb: str) -> bool:
+    """Validate TAG verb.
+
+    Args:
+        verb: Verb to validate
+
+    Returns:
+        True if verb is valid, False otherwise
+
+    Examples:
+        >>> validate_verb("impl")
+        True
+        >>> validate_verb("invalid")
+        False
+    """
+    return isinstance(verb, str) and verb in VALID_VERBS
+
+
+def get_default_verb() -> str:
+    """Get default TAG verb.
+
+    Returns:
+        Default verb string ("impl")
+    """
+    return DEFAULT_VERB
+
+
+def validate_tag(tag: TAG) -> Tuple[bool, List[str]]:
+    """Validate complete TAG.
+
+    Args:
+        tag: TAG to validate
+
+    Returns:
+        Tuple of (is_valid, error_messages)
+        - is_valid: True if TAG is valid
+        - error_messages: List of validation errors (empty if valid)
+
+    Examples:
+        >>> tag = TAG("SPEC-AUTH-001", Path("test.py"), 1, "impl")
+        >>> is_valid, errors = validate_tag(tag)
+        >>> is_valid
+        True
+    """
+    errors = []
+
+    # Validate SPEC-ID format
+    if not validate_spec_id_format(tag.spec_id):
+        errors.append(
+            f"Invalid SPEC-ID format: '{tag.spec_id}'. "
+            f"Expected format: SPEC-{{DOMAIN}}-{{NUMBER}} (e.g., SPEC-AUTH-001)"
+        )
+
+    # Validate verb
+    if not validate_verb(tag.verb):
+        errors.append(f"Invalid verb: '{tag.verb}'. Valid verbs: {', '.join(sorted(VALID_VERBS))}")
+
+    return len(errors) == 0, errors
+
+
+def parse_tag_string(comment: str, file_path: Path, line: int) -> TAG | None:
+    """Parse TAG from comment string.
+
+    Args:
+        comment: Comment string to parse
+        file_path: Path to the file containing the comment
+        line: Line number of the comment
+
+    Returns:
+        TAG object if valid TAG found, None otherwise
+
+    Examples:
+        >>> comment = "# @SPEC SPEC-AUTH-001"
+        >>> tag = parse_tag_string(comment, Path("test.py"), 1)
+        >>> tag.spec_id
+        'SPEC-AUTH-001'
+        >>> tag.verb
+        'impl'
+    """
+    if not isinstance(comment, str):
+        return None
+
+    # Remove leading whitespace and comment character
+    comment = comment.strip()
+
+    # Check if comment starts with #
+    if not comment.startswith("#"):
+        # Not a comment
+        return None
+
+    # Remove # and leading whitespace
+    comment = comment[1:].strip()
+
+    # Check for @SPEC prefix
+    if not comment.startswith("@SPEC"):
+        return None
+
+    # Remove @SPEC prefix
+    comment = comment[5:].strip()  # len("@SPEC") == 5
+
+    # Split into parts
+    parts = comment.split()
+
+    if not parts:
+        return None
+
+    # First part is SPEC-ID
+    spec_id = parts[0]
+
+    # Validate SPEC-ID format
+    if not validate_spec_id_format(spec_id):
+        return None
+
+    # Second part (if present) is verb
+    verb = DEFAULT_VERB
+    if len(parts) > 1 and parts[1] in VALID_VERBS:
+        verb = parts[1]
+
+    return TAG(spec_id=spec_id, file_path=file_path, line=line, verb=verb)
+
+
+__all__ = [
+    "TAG",
+    "VALID_VERBS",
+    "DEFAULT_VERB",
+    "validate_spec_id_format",
+    "validate_verb",
+    "get_default_verb",
+    "validate_tag",
+    "parse_tag_string",
+]

moai_adk/templates/.claude/hooks/moai/lib/timeout.py

@@ -15,7 +15,7 @@ import platform
 import signal
 import threading
 from contextlib import contextmanager
-from typing import Any, Callable, Optional
+from typing import Any, Callable
 
 
 class TimeoutError(Exception):
@@ -44,7 +44,7 @@ class CrossPlatformTimeout:
             timeout.cancel()
     """
 
-    def __init__(self, timeout_seconds: float, callback: Optional[Callable] = None):
+    def __init__(self, timeout_seconds: float, callback: Callable | None = None):
         """Initialize timeout with duration in seconds.
 
         Args:
@@ -55,9 +55,9 @@ class CrossPlatformTimeout:
         self.timeout_seconds = timeout_seconds
         self.timeout_seconds_int = max(1, int(timeout_seconds))  # signal.alarm requires >=1
         self.callback = callback
-        self.timer: Optional[threading.Timer] = None
+        self.timer: threading.Timer | None = None
         self._is_windows = platform.system() == "Windows"
-        self._old_handler: Optional[signal.Handlers | Callable[[int, Any], Any]] = None
+        self._old_handler: signal.Handlers | Callable[[int, Any], Any] = None
 
     def start(self) -> None:
         """Start timeout countdown."""
@@ -138,7 +138,7 @@ class CrossPlatformTimeout:
 
 
 @contextmanager
-def timeout_context(timeout_seconds: float, callback: Optional[Callable] = None):
+def timeout_context(timeout_seconds: float, callback: Callable | None = None):
     """Decorator/context manager for timeout.
 
     Usage: