moai-adk 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

moai_adk/core/tags/generator.py

@@ -0,0 +1,109 @@
+# @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

@@ -0,0 +1,99 @@
+# @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

@@ -0,0 +1,126 @@
+# @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

@@ -0,0 +1,76 @@
+# @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)