moai-adk 0.8.1__py3-none-any.whl → 0.8.3__py3-none-any.whl

moai_adk/templates/src/moai_adk/core/tags/cli.py

@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+# @CODE:DOC-TAG-004 | Component 3: CLI utility for TAG validation
+"""CLI utility for moai-adk validate-tags command
+
+This module provides a command-line interface to the central TAG validator:
+- Validate files or directories
+- Generate reports in multiple formats (detailed, summary, JSON)
+- Support various validation modes (strict, custom patterns)
+- Save reports to files
+
+Usage:
+    moai-adk validate-tags .
+    moai-adk validate-tags --strict src/
+    moai-adk validate-tags --format json --output report.json
+    moai-adk validate-tags --no-duplicates --no-orphans
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+from .validator import (
+    CentralValidationResult,
+    CentralValidator,
+    ValidationConfig,
+)
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create argument parser for CLI
+
+    Returns:
+        ArgumentParser with all CLI options
+    """
+    parser = argparse.ArgumentParser(
+        prog="moai-adk validate-tags",
+        description="Validate TAG annotations in MoAI-ADK projects",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  moai-adk validate-tags .                          # Validate entire project
+  moai-adk validate-tags --strict src/              # Strict validation of src/
+  moai-adk validate-tags --format json              # JSON report output
+  moai-adk validate-tags --output report.json       # Save report to file
+  moai-adk validate-tags --no-orphans               # Disable orphan checking
+  moai-adk validate-tags --file-types py,js,md      # Validate specific file types
+
+Report Formats:
+  detailed  - Full report with all issues, locations, and suggestions (default)
+  summary   - Concise summary with statistics only
+  json      - Machine-readable JSON format
+
+Validation Modes:
+  Normal    - Errors block, warnings reported but pass
+  Strict    - Both errors and warnings block (use --strict flag)
+        """
+    )
+
+    # Positional argument
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Path to file or directory to validate (default: current directory)"
+    )
+
+    # Validation options
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat warnings as errors (block on warnings)"
+    )
+
+    parser.add_argument(
+        "--no-duplicates",
+        action="store_true",
+        help="Disable duplicate TAG checking"
+    )
+
+    parser.add_argument(
+        "--no-orphans",
+        action="store_true",
+        help="Disable orphan TAG checking"
+    )
+
+    parser.add_argument(
+        "--no-chain-check",
+        action="store_true",
+        help="Disable TAG chain integrity checking"
+    )
+
+    # File filtering options
+    parser.add_argument(
+        "--file-types",
+        help="Comma-separated file types to validate (e.g., py,js,ts)"
+    )
+
+    parser.add_argument(
+        "--ignore-patterns",
+        help="Comma-separated glob patterns to ignore (e.g., .git/*,*.pyc)"
+    )
+
+    # Report options
+    parser.add_argument(
+        "--format",
+        choices=["detailed", "summary", "json"],
+        default="detailed",
+        help="Report format (default: detailed)"
+    )
+
+    parser.add_argument(
+        "--output",
+        "-o",
+        help="Output file path (default: stdout)"
+    )
+
+    # Quiet mode
+    parser.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        help="Suppress output, only return exit code"
+    )
+
+    # Version
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="moai-adk 0.7.0"
+    )
+
+    return parser
+
+
+def validate_path(path_str: str) -> Optional[Path]:
+    """Validate that path exists
+
+    Args:
+        path_str: Path string to validate
+
+    Returns:
+        Path object if valid, None otherwise
+    """
+    path = Path(path_str)
+    if not path.exists():
+        print(f"Error: Path does not exist: {path_str}", file=sys.stderr)
+        return None
+    return path
+
+
+def create_config_from_args(args: argparse.Namespace) -> ValidationConfig:
+    """Create ValidationConfig from CLI arguments
+
+    Args:
+        args: Parsed command-line arguments
+
+    Returns:
+        ValidationConfig object
+    """
+    config = ValidationConfig(
+        strict_mode=args.strict,
+        check_duplicates=not args.no_duplicates,
+        check_orphans=not args.no_orphans,
+        check_chain_integrity=not args.no_chain_check,
+        report_format=args.format
+    )
+
+    # Parse file types if provided
+    if args.file_types:
+        config.allowed_file_types = [
+            ft.strip() for ft in args.file_types.split(",")
+        ]
+
+    # Parse ignore patterns if provided
+    if args.ignore_patterns:
+        config.ignore_patterns = [
+            pattern.strip() for pattern in args.ignore_patterns.split(",")
+        ]
+
+    return config
+
+
+def run_validation(path: Path, config: ValidationConfig) -> CentralValidationResult:
+    """Run validation on path
+
+    Args:
+        path: Path to validate (file or directory)
+        config: ValidationConfig object
+
+    Returns:
+        CentralValidationResult
+    """
+    validator = CentralValidator(config=config)
+
+    if path.is_file():
+        result = validator.validate_files([str(path)])
+    else:
+        result = validator.validate_directory(str(path))
+
+    return result
+
+
+def output_report(
+    result: CentralValidationResult,
+    validator: CentralValidator,
+    format: str,
+    output_file: Optional[str],
+    quiet: bool
+) -> None:
+    """Output validation report
+
+    Args:
+        result: CentralValidationResult
+        validator: CentralValidator instance
+        format: Report format (detailed|summary|json)
+        output_file: Output file path (None for stdout)
+        quiet: Suppress output if True
+    """
+    if quiet:
+        return
+
+    # Generate report
+    report = validator.create_report(result, format=format)
+
+    # Output to file or stdout
+    if output_file:
+        try:
+            with open(output_file, 'w') as f:
+                f.write(report)
+            print(f"Report saved to: {output_file}", file=sys.stderr)
+        except Exception as e:
+            print(f"Error writing report: {e}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        print(report)
+
+
+def main(argv: Optional[list] = None) -> int:
+    """Main CLI entry point
+
+    Args:
+        argv: Command-line arguments (default: sys.argv[1:])
+
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    # Validate path
+    path = validate_path(args.path)
+    if path is None:
+        return 1
+
+    # Create configuration from args
+    config = create_config_from_args(args)
+
+    # Run validation
+    try:
+        result = run_validation(path, config)
+    except Exception as e:
+        print(f"Validation error: {e}", file=sys.stderr)
+        return 1
+
+    # Create validator for report generation
+    validator = CentralValidator(config=config)
+
+    # Output report
+    output_report(
+        result=result,
+        validator=validator,
+        format=args.format,
+        output_file=args.output,
+        quiet=args.quiet
+    )
+
+    # Return exit code
+    return 0 if result.is_valid else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

moai_adk/templates/src/moai_adk/core/tags/pre_commit_validator.py

@@ -0,0 +1,355 @@
+#!/usr/bin/env python3
+# @CODE:DOC-TAG-004 | Component 1: Pre-commit TAG validator
+"""Pre-commit TAG validation module
+
+This module provides validation functionality for TAG annotations:
+- Format validation (@DOC:DOMAIN-TYPE-NNN)
+- Duplicate TAG detection across files
+- Orphan TAG detection (CODE without TEST, etc.)
+- Git staged file scanning
+
+Used by pre-commit hooks to ensure TAG quality.
+"""
+
+import re
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+@dataclass
+class ValidationError:
+    """Validation error with file location information"""
+    message: str
+    tag: str
+    locations: List[Tuple[str, int]] = field(default_factory=list)
+
+    def __str__(self) -> str:
+        loc_str = ", ".join([f"{f}:{l}" for f, l in self.locations])
+        return f"{self.message}: {self.tag} at {loc_str}"
+
+
+@dataclass
+class ValidationWarning:
+    """Validation warning with file location"""
+    message: str
+    tag: str
+    location: Tuple[str, int]
+
+    def __str__(self) -> str:
+        return f"{self.message}: {self.tag} at {self.location[0]}:{self.location[1]}"
+
+
+@dataclass
+class ValidationResult:
+    """Complete validation result"""
+    is_valid: bool
+    errors: List[ValidationError] = field(default_factory=list)
+    warnings: List[ValidationWarning] = field(default_factory=list)
+
+    def format(self) -> str:
+        """Format result for display"""
+        lines = []
+
+        if self.errors:
+            lines.append("Errors:")
+            for error in self.errors:
+                lines.append(f"  - {error}")
+
+        if self.warnings:
+            lines.append("\nWarnings:")
+            for warning in self.warnings:
+                lines.append(f"  - {warning}")
+
+        if not self.errors and not self.warnings:
+            lines.append("No issues found.")
+
+        return "\n".join(lines)
+
+
+class PreCommitValidator:
+    """Pre-commit TAG validator
+
+    Validates TAG annotations in files:
+    - Format: @DOC:DOMAIN-TYPE-NNN
+    - No duplicates
+    - No orphans (CODE without TEST)
+
+    Args:
+        strict_mode: Treat warnings as errors
+        check_orphans: Enable orphan TAG detection
+        tag_pattern: Custom TAG regex pattern
+    """
+
+    # Default TAG pattern: @(SPEC|CODE|TEST|DOC):DOMAIN-NNN or DOMAIN-TYPE-NNN
+    # Matches formats like:
+    # - @CODE:AUTH-API-001 (domain-type-number)
+    # - @CODE:SPEC-001 (domain-number)
+    # - @TEST:USER-REG-001 (domain-type-number)
+    DEFAULT_TAG_PATTERN = r"@(SPEC|CODE|TEST|DOC):([A-Z]+(?:-[A-Z]+)*-\d{3})"
+
+    def __init__(
+        self,
+        strict_mode: bool = False,
+        check_orphans: bool = True,
+        tag_pattern: Optional[str] = None
+    ):
+        self.strict_mode = strict_mode
+        self.check_orphans = check_orphans
+        self.tag_pattern = re.compile(tag_pattern or self.DEFAULT_TAG_PATTERN)
+
+    def validate_format(self, tag: str) -> bool:
+        """Validate TAG format
+
+        Args:
+            tag: TAG string (e.g., "@CODE:AUTH-API-001")
+
+        Returns:
+            True if format is valid
+        """
+        return bool(self.tag_pattern.match(tag))
+
+    def extract_tags(self, content: str) -> List[str]:
+        """Extract all TAGs from content
+
+        Args:
+            content: File content
+
+        Returns:
+            List of TAG strings
+        """
+        matches = self.tag_pattern.findall(content)
+        # Convert tuples to full TAG strings
+        tags = [f"@{prefix}:{domain}" for prefix, domain in matches]
+        return tags
+
+    def validate_duplicates(self, files: List[str]) -> List[ValidationError]:
+        """Detect duplicate TAGs
+
+        Args:
+            files: List of file paths to scan
+
+        Returns:
+            List of validation errors for duplicates
+        """
+        errors: List[ValidationError] = []
+        tag_locations: Dict[str, List[Tuple[str, int]]] = {}
+
+        for filepath in files:
+            try:
+                path = Path(filepath)
+                if not path.exists() or not path.is_file():
+                    continue
+
+                content = path.read_text(encoding="utf-8", errors="ignore")
+                lines = content.splitlines()
+
+                for line_num, line in enumerate(lines, start=1):
+                    tags = self.extract_tags(line)
+                    for tag in tags:
+                        if tag not in tag_locations:
+                            tag_locations[tag] = []
+                        tag_locations[tag].append((filepath, line_num))
+
+            except Exception:
+                # Skip files that can't be read
+                continue
+
+        # Find duplicates
+        for tag, locations in tag_locations.items():
+            if len(locations) > 1:
+                errors.append(ValidationError(
+                    message="Duplicate TAG found",
+                    tag=tag,
+                    locations=locations
+                ))
+
+        return errors
+
+    def validate_orphans(self, files: List[str]) -> List[ValidationWarning]:
+        """Detect orphan TAGs
+
+        Orphan TAGs are:
+        - @CODE without corresponding @TEST
+        - @TEST without corresponding @CODE
+        - @SPEC without implementation
+
+        Args:
+            files: List of file paths to scan
+
+        Returns:
+            List of validation warnings
+        """
+        if not self.check_orphans:
+            return []
+
+        warnings: List[ValidationWarning] = []
+
+        # Collect all TAGs by type and domain
+        tags_by_type: Dict[str, Dict[str, List[Tuple[str, int]]]] = {
+            "SPEC": {},
+            "CODE": {},
+            "TEST": {},
+            "DOC": {}
+        }
+
+        for filepath in files:
+            try:
+                path = Path(filepath)
+                if not path.exists() or not path.is_file():
+                    continue
+
+                content = path.read_text(encoding="utf-8", errors="ignore")
+                lines = content.splitlines()
+
+                for line_num, line in enumerate(lines, start=1):
+                    matches = self.tag_pattern.findall(line)
+                    for prefix, domain in matches:
+                        tag = f"@{prefix}:{domain}"
+                        if domain not in tags_by_type[prefix]:
+                            tags_by_type[prefix][domain] = []
+                        tags_by_type[prefix][domain].append((filepath, line_num))
+
+            except Exception:
+                continue
+
+        # Check for orphans
+        # CODE without TEST
+        for domain, locations in tags_by_type["CODE"].items():
+            if domain not in tags_by_type["TEST"]:
+                for filepath, line_num in locations:
+                    warnings.append(ValidationWarning(
+                        message="CODE TAG without corresponding TEST",
+                        tag=f"@CODE:{domain}",
+                        location=(filepath, line_num)
+                    ))
+
+        # TEST without CODE
+        for domain, locations in tags_by_type["TEST"].items():
+            if domain not in tags_by_type["CODE"]:
+                for filepath, line_num in locations:
+                    warnings.append(ValidationWarning(
+                        message="TEST TAG without corresponding CODE",
+                        tag=f"@TEST:{domain}",
+                        location=(filepath, line_num)
+                    ))
+
+        return warnings
+
+    def get_staged_files(self, repo_path: str = ".") -> List[str]:
+        """Get list of staged files from git
+
+        Args:
+            repo_path: Git repository path
+
+        Returns:
+            List of staged file paths
+        """
+        try:
+            result = subprocess.run(
+                ["git", "diff", "--name-only", "--cached"],
+                cwd=repo_path,
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=True
+            )
+            files = [
+                line.strip()
+                for line in result.stdout.splitlines()
+                if line.strip()
+            ]
+            return files
+        except Exception:
+            return []
+
+    def validate_files(self, files: List[str]) -> ValidationResult:
+        """Validate list of files
+
+        Main validation method that runs all checks:
+        - Format validation
+        - Duplicate detection
+        - Orphan detection
+
+        Args:
+            files: List of file paths to validate
+
+        Returns:
+            ValidationResult with errors and warnings
+        """
+        if not files:
+            return ValidationResult(is_valid=True)
+
+        # Check for duplicates
+        errors = self.validate_duplicates(files)
+
+        # Check for orphans
+        warnings = self.validate_orphans(files)
+
+        # In strict mode, warnings become errors
+        if self.strict_mode and warnings:
+            is_valid = False
+        else:
+            is_valid = len(errors) == 0
+
+        return ValidationResult(
+            is_valid=is_valid,
+            errors=errors,
+            warnings=warnings
+        )
+
+
+def main():
+    """CLI entry point for pre-commit hook"""
+    import argparse
+    import sys
+
+    parser = argparse.ArgumentParser(
+        description="Validate TAG annotations in git staged files"
+    )
+    parser.add_argument(
+        "--files",
+        nargs="*",
+        help="Files to validate (default: git staged files)"
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat warnings as errors"
+    )
+    parser.add_argument(
+        "--no-orphan-check",
+        action="store_true",
+        help="Disable orphan TAG checking"
+    )
+
+    args = parser.parse_args()
+
+    validator = PreCommitValidator(
+        strict_mode=args.strict,
+        check_orphans=not args.no_orphan_check
+    )
+
+    # Get files to validate
+    if args.files:
+        files = args.files
+    else:
+        files = validator.get_staged_files()
+
+    if not files:
+        print("No files to validate.")
+        sys.exit(0)
+
+    # Run validation
+    result = validator.validate_files(files)
+
+    # Print results
+    print(result.format())
+
+    # Exit with error code if validation failed
+    sys.exit(0 if result.is_valid else 1)
+
+
+if __name__ == "__main__":
+    main()