moai-adk 0.15.0__py3-none-any.whl → 0.25.4__py3-none-any.whl

moai_adk/core/tags/cli.py

@@ -1,283 +0,0 @@
-#!/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/core/tags/generator.py

@@ -1,109 +0,0 @@
-# @CODE:GEN-001, @CODE:GEN-002
-"""TAG ID generation and duplicate detection.
-
-Generates sequential @DOC:DOMAIN-NNN identifiers and detects duplicates
-using ripgrep for performance.
-
-@SPEC:DOC-TAG-001: @DOC tag automatic generation infrastructure
-"""
-
-import re
-import subprocess
-from typing import List
-
-# Domain validation: Must start with letter, alphanumeric + hyphens, end with alphanumeric
-DOMAIN_PATTERN = re.compile(r"^[A-Z]([A-Z0-9-]*[A-Z0-9])?$")
-
-
-def generate_doc_tag(domain: str, existing_ids: List[str]) -> str:
-    """Generate next available @DOC tag ID for domain.
-
-    Validates domain format (uppercase alphanumeric, hyphens allowed).
-    Finds highest current number and increments by 1.
-
-    Args:
-        domain: Domain name (e.g., "AUTH", "CLI-TOOL")
-        existing_ids: List of existing TAG IDs for this domain
-
-    Returns:
-        Next TAG ID (e.g., "@DOC:AUTH-003")
-
-    Raises:
-        ValueError: Invalid domain format
-
-    Examples:
-        >>> generate_doc_tag("AUTH", [])
-        '@DOC:AUTH-001'
-        >>> generate_doc_tag("AUTH", ["@DOC:AUTH-001", "@DOC:AUTH-002"])
-        '@DOC:AUTH-003'
-    """
-    # Validate domain format: uppercase alphanumeric and hyphens only
-    if not DOMAIN_PATTERN.match(domain):
-        raise ValueError(
-            f"Invalid domain format: {domain}. "
-            "Domain must be uppercase, start with a letter, "
-            "and contain only alphanumeric characters and hyphens."
-        )
-
-    # Find max number from existing IDs for this domain
-    max_num = 0
-    pattern = rf"@DOC:{re.escape(domain)}-(\d{{3}})$"
-
-    for tag_id in existing_ids:
-        match = re.search(pattern, tag_id)
-        if match:
-            num = int(match.group(1))
-            max_num = max(max_num, num)
-
-    # Generate next ID
-    next_num = max_num + 1
-    return f"@DOC:{domain}-{next_num:03d}"
-
-
-def detect_duplicates(domain: str, search_path: str = "docs/") -> List[str]:
-    """Detect existing @DOC tags using ripgrep.
-
-    Performs efficient ripgrep search for all @DOC:DOMAIN-NNN tags.
-
-    Args:
-        domain: Domain to search for
-        search_path: Directory to search (default: docs/)
-
-    Returns:
-        List of existing TAG IDs
-
-    Raises:
-        RuntimeError: ripgrep not available or execution error
-
-    Examples:
-        >>> detect_duplicates("AUTH", "docs/")
-        ['@DOC:AUTH-001', '@DOC:AUTH-002']
-    """
-    try:
-        result = subprocess.run(
-            ["rg", rf"@DOC:{re.escape(domain)}-\d{{3}}", search_path, "-o", "--no-heading"],
-            capture_output=True,
-            text=True,
-            timeout=5,
-        )
-
-        if result.returncode == 0:
-            # Found matches
-            return [tag.strip() for tag in result.stdout.strip().split("\n") if tag.strip()]
-        elif result.returncode == 1:
-            # No matches found (normal case for new domains)
-            return []
-        else:
-            # ripgrep error
-            raise RuntimeError(f"ripgrep error: {result.stderr}")
-
-    except FileNotFoundError:
-        raise RuntimeError(
-            "ripgrep (rg) not found in PATH. Please install it: "
-            "brew install ripgrep (macOS) or apt install ripgrep (Linux)"
-        )
-    except subprocess.TimeoutExpired:
-        raise RuntimeError(
-            f"ripgrep timeout after 5 seconds searching {search_path}. "
-            "Consider narrowing the search path."
-        )

moai_adk/core/tags/inserter.py

@@ -1,99 +0,0 @@
-# @CODE:INS-001, @CODE:INS-002
-"""Markdown TAG insertion and file operations.
-
-Inserts @DOC tags into markdown file headers with chain references
-and provides backup/recovery functionality.
-
-@SPEC:DOC-TAG-001: @DOC tag automatic generation infrastructure
-"""
-
-from pathlib import Path
-from typing import Optional
-
-
-def format_tag_header(tag_id: str, chain_ref: Optional[str] = None) -> str:
-    """Format TAG header comment with chain reference.
-
-    Args:
-        tag_id: TAG ID (e.g., "@DOC:AUTH-001")
-        chain_ref: Chain reference (e.g., "@SPEC:AUTH-001")
-
-    Returns:
-        Formatted header comment
-
-    Examples:
-        >>> format_tag_header("@DOC:AUTH-001", "@SPEC:AUTH-001")
-        '# @DOC:AUTH-001 | Chain: @SPEC:AUTH-001 -> @DOC:AUTH-001'
-    """
-    if chain_ref:
-        return f"# {tag_id} | Chain: {chain_ref} -> {tag_id}"
-    return f"# {tag_id}"
-
-
-def insert_tag_to_markdown(
-    file_path: Path, tag_id: str, chain_ref: Optional[str] = None
-) -> bool:
-    """Insert TAG comment into markdown file header.
-
-    Inserts TAG as first line before the document title.
-    Creates backup before modification.
-
-    Args:
-        file_path: Path to markdown file
-        tag_id: TAG ID to insert
-        chain_ref: Optional chain reference
-
-    Returns:
-        True if successful, False on error
-
-    Examples:
-        >>> insert_tag_to_markdown(Path("guide.md"), "@DOC:AUTH-001", "@SPEC:AUTH-001")
-        True
-    """
-    try:
-        # Read original content
-        content = file_path.read_text(encoding="utf-8")
-
-        # Format TAG header
-        tag_header = format_tag_header(tag_id, chain_ref)
-
-        # Insert at beginning
-        new_content = f"{tag_header}\n{content}"
-
-        # Write back
-        file_path.write_text(new_content, encoding="utf-8")
-
-        return True
-
-    except (FileNotFoundError, PermissionError, OSError) as e:
-        # Handle file operation errors gracefully
-        print(f"Error inserting TAG into {file_path}: {e}")
-        return False
-
-
-def create_backup(file_path: Path, backup_dir: Path = Path(".moai/backups")) -> Optional[Path]:
-    """Create backup of file before modification.
-
-    Args:
-        file_path: Path to file to backup
-        backup_dir: Directory for backups
-
-    Returns:
-        Path to backup file or None on error
-
-    Examples:
-        >>> create_backup(Path("guide.md"))
-        Path('.moai/backups/guide.md.bak')
-    """
-    try:
-        backup_dir.mkdir(parents=True, exist_ok=True)
-        backup_path = backup_dir / f"{file_path.name}.bak"
-
-        content = file_path.read_text(encoding="utf-8")
-        backup_path.write_text(content, encoding="utf-8")
-
-        return backup_path
-
-    except (FileNotFoundError, PermissionError, OSError) as e:
-        print(f"Error creating backup for {file_path}: {e}")
-        return None

moai_adk/core/tags/mapper.py

@@ -1,126 +0,0 @@
-# @CODE:MAP-001, @CODE:MAP-002
-"""SPEC-DOC mapping and confidence scoring.
-
-Maps documentation files to related SPEC IDs based on domain matching
-and calculates confidence scores for chain references.
-
-@SPEC:DOC-TAG-001: @DOC tag automatic generation infrastructure
-"""
-
-import re
-from pathlib import Path
-from typing import Any, Optional
-
-from moai_adk.core.tags.parser import extract_spec_id, parse_domain
-
-
-def find_related_spec(doc_path: Path, specs_dir: Path = Path(".moai/specs")) -> Optional[str]:
-    """Find related SPEC ID by matching domain from document path.
-
-    Searches for SPEC directories matching the domain inferred from the
-    document's file path. Returns the most recent SPEC (highest number)
-    if multiple matches exist.
-
-    Args:
-        doc_path: Path to documentation file (e.g., docs/auth/setup.md)
-        specs_dir: Path to SPEC directory (default: .moai/specs)
-
-    Returns:
-        SPEC ID (e.g., "AUTH-001") or None if no match found
-
-    Examples:
-        >>> find_related_spec(Path("docs/auth/guide.md"))
-        'AUTH-001'
-        >>> find_related_spec(Path("docs/api/endpoints.md"))
-        'API-001'
-    """
-    # Extract potential domain from file path
-    # E.g., docs/auth/setup.md -> 'auth'
-    path_parts = doc_path.parts
-    if len(path_parts) < 2:
-        return None
-
-    # Get the first directory under 'docs/' as potential domain
-    potential_domain = path_parts[1] if path_parts[0] == "docs" else path_parts[0]
-    potential_domain = potential_domain.upper().replace("_", "-")
-
-    # Search for matching SPEC directories
-    if not specs_dir.exists():
-        return None
-
-    matching_specs = []
-    for spec_dir in specs_dir.glob("SPEC-*"):
-        spec_file = spec_dir / "spec.md"
-        if not spec_file.exists():
-            continue
-
-        try:
-            with open(spec_file, "r", encoding="utf-8") as f:
-                content = f.read()
-                spec_id = extract_spec_id(content)
-                spec_domain = parse_domain(spec_id)
-
-                # Case-insensitive domain match
-                if spec_domain.upper() == potential_domain:
-                    matching_specs.append(spec_id)
-        except (ValueError, OSError):
-            # Skip invalid or unreadable SPEC files
-            continue
-
-    if not matching_specs:
-        return None
-
-    # Return most recent SPEC (highest number)
-    def extract_number(spec: str) -> int:
-        match: Any = re.search(r"-(\d{3})$", spec)
-        return int(match.group(1)) if match else 0
-
-    matching_specs.sort(key=extract_number, reverse=True)
-    return str(matching_specs[0])
-
-
-def calculate_confidence(spec_id: str, doc_path: Path) -> float:
-    """Calculate confidence score for SPEC-DOC mapping.
-
-    Confidence levels:
-    - 0.95+: Exact SPEC ID in file path
-    - 0.80+: Domain match + relevant keywords in filename
-    - 0.50+: Domain match only
-    - <0.50: No domain match
-
-    Args:
-        spec_id: SPEC ID (e.g., "AUTH-001")
-        doc_path: Path to documentation file
-
-    Returns:
-        Confidence score (0.0 to 1.0)
-
-    Examples:
-        >>> calculate_confidence("AUTH-001", Path("docs/auth/AUTH-001-impl.md"))
-        0.95
-        >>> calculate_confidence("AUTH-001", Path("docs/auth/authentication.md"))
-        0.85
-        >>> calculate_confidence("AUTH-001", Path("docs/api/guide.md"))
-        0.2
-    """
-    doc_str = str(doc_path).lower()
-    spec_id_lower = spec_id.lower()
-    domain = parse_domain(spec_id).lower()
-
-    # Exact SPEC ID match in path
-    if spec_id_lower in doc_str:
-        return 0.95
-
-    # Domain match + relevant keywords
-    if domain in doc_str:
-        # Keywords related to the domain
-        keywords = [domain, "guide", "setup", "implementation", "tutorial"]
-        keyword_matches = sum(1 for kw in keywords if kw in doc_str)
-
-        if keyword_matches >= 2:
-            return 0.80
-        else:
-            return 0.50
-
-    # No domain match
-    return 0.20

moai_adk/core/tags/parser.py

@@ -1,76 +0,0 @@
-# @CODE:PAR-001 | Chain: @SPEC:DOC-TAG-001 -> @CODE:PAR-001
-"""SPEC parser utilities for TAG generation system.
-
-This module extracts SPEC metadata (ID, domain, title) from SPEC documents
-for use in TAG generation and SPEC-DOC mapping.
-
-@SPEC:DOC-TAG-001: @DOC tag automatic generation infrastructure
-"""
-
-import re
-from typing import Any
-
-import yaml
-
-
-def extract_spec_id(spec_content: str) -> str:
-    """Extract SPEC ID from YAML frontmatter.
-
-    Args:
-        spec_content: Full content of SPEC markdown file
-
-    Returns:
-        SPEC ID (e.g., "AUTH-001")
-
-    Raises:
-        ValueError: If YAML frontmatter or ID not found
-
-    Examples:
-        >>> content = "---\\nid: AUTH-001\\n---\\n# SPEC"
-        >>> extract_spec_id(content)
-        'AUTH-001'
-    """
-    # Find YAML frontmatter between --- markers
-    match = re.search(r"^---\s*\n(.*?)\n---\s*$", spec_content, re.MULTILINE | re.DOTALL)
-    if not match:
-        raise ValueError("YAML frontmatter not found in SPEC document")
-
-    # Parse YAML
-    yaml_content = match.group(1)
-    try:
-        metadata: Any = yaml.safe_load(yaml_content)
-        spec_id: Any = metadata.get("id")
-        if not spec_id:
-            raise ValueError("'id' field not found in YAML frontmatter")
-        return str(spec_id)
-    except yaml.YAMLError as e:
-        raise ValueError(f"Invalid YAML frontmatter: {e}")
-
-
-def parse_domain(spec_id: str) -> str:
-    """Extract domain from SPEC ID.
-
-    The domain is everything before the final -NNN sequence.
-
-    Examples:
-        >>> parse_domain("AUTH-001")
-        'AUTH'
-        >>> parse_domain("CLI-TOOL-001")
-        'CLI-TOOL'
-        >>> parse_domain("DOC-TAG-001")
-        'DOC-TAG'
-
-    Args:
-        spec_id: Full SPEC ID
-
-    Returns:
-        Domain part (everything before last "-NNN")
-
-    Raises:
-        ValueError: Invalid SPEC ID format
-    """
-    # Match pattern: any chars followed by hyphen and exactly 3 digits at end
-    match = re.match(r"^(.*?)-\d{3}$", spec_id)
-    if not match:
-        raise ValueError(f"Invalid SPEC ID format: {spec_id}")
-    return match.group(1)